The reference below is generated from the Sema OpenAPI specification. All endpoints are prefixed with /v1 and use the base URL https://dev-api.withsema.com. For authentication (API key or OIDC), see API Overview. For error codes and response shapes, see Errors.
Sema Ingest Gateway 0.1.0¶
Universal inbox and enrichment pipeline for AI agent products
inboxes¶
POST /v1/inboxes¶
Create inbox
Description
Create a new inbox for receiving items.
By default, the inbox is owned by the authenticated user. You can optionally specify an organization as the owner.
Required permission: inbox:create
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Request body
{
"name": "string",
"description": null,
"webhook_url": null,
"webhook_secret": null,
"owner_type": null,
"owner_id": null,
"email_enabled": true,
"email_prefix": null
}
Schema of the request body
{
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"title": "Name",
"description": "Human-readable name for the inbox",
"examples": [
"Customer Support",
"Invoice Processing"
]
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 1000
},
{
"type": "null"
}
],
"title": "Description",
"description": "Optional description of the inbox purpose",
"examples": [
"Inbox for customer support emails"
]
},
"webhook_url": {
"anyOf": [
{
"type": "string",
"maxLength": 2048
},
{
"type": "null"
}
],
"title": "Webhook Url",
"description": "Webhook URL for delivery notifications",
"examples": [
"https://api.example.com/webhooks/inbox"
]
},
"webhook_secret": {
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
],
"title": "Webhook Secret",
"description": "Secret for signing webhook payloads (Standard Webhooks format)"
},
"owner_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Owner Type",
"description": "Owner type: 'user' or 'organization'. Defaults to 'user' (current user).",
"examples": [
"user",
"organization"
]
},
"owner_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Owner Id",
"description": "Owner ID. If owner_type is 'user' and this is None, defaults to the authenticated user."
},
"email_enabled": {
"type": "boolean",
"title": "Email Enabled",
"description": "Whether email receiving is enabled for this inbox",
"default": false
},
"email_prefix": {
"anyOf": [
{
"type": "string",
"maxLength": 64,
"pattern": "^[a-z0-9]([a-z0-9\\-]*[a-z0-9])?$"
},
{
"type": "null"
}
],
"title": "Email Prefix",
"description": "Email prefix (part before @). Auto-generated from name if not provided.",
"examples": [
"support",
"invoices"
]
}
},
"type": "object",
"required": [
"name"
],
"title": "CreateInboxRequest",
"description": "Request body for creating an inbox."
}
Response 201 Created
{
"id": "63d78962-eb09-4dbc-9fc7-61f2c4673653",
"name": "string",
"description": null,
"owner_type": "string",
"owner_id": "6de74340-6696-4c4e-bff3-2eb7ad1611f3",
"owner_name": null,
"owner_email": null,
"email_enabled": true,
"email_address": null,
"api_enabled": true,
"allowed_senders": [
"string"
],
"allowed_domains": [
"string"
],
"webhook_url": null,
"webhook_configured": true,
"payload_mode": "string",
"enrichment_pipeline": {},
"is_active": true,
"item_count": 0,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z"
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id",
"description": "Unique inbox identifier"
},
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"description": "Inbox description"
},
"owner_type": {
"type": "string",
"title": "Owner Type",
"description": "Owner type: 'user' or 'organization'"
},
"owner_id": {
"type": "string",
"format": "uuid",
"title": "Owner Id",
"description": "Owner ID"
},
"owner_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Owner Name",
"description": "Owner's display name"
},
"owner_email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Owner Email",
"description": "Owner's email (for users)"
},
"email_enabled": {
"type": "boolean",
"title": "Email Enabled",
"description": "Whether email receiving is enabled"
},
"email_address": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Email Address",
"description": "Email address for receiving (if enabled)"
},
"api_enabled": {
"type": "boolean",
"title": "Api Enabled",
"description": "Whether API receiving is enabled"
},
"allowed_senders": {
"items": {
"type": "string"
},
"type": "array",
"title": "Allowed Senders",
"description": "Allowed sender emails"
},
"allowed_domains": {
"items": {
"type": "string"
},
"type": "array",
"title": "Allowed Domains",
"description": "Allowed sender domains"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Webhook Url",
"description": "Webhook URL for delivery"
},
"webhook_configured": {
"type": "boolean",
"title": "Webhook Configured",
"description": "Whether webhook is configured"
},
"payload_mode": {
"type": "string",
"title": "Payload Mode",
"description": "Webhook payload mode: 'full' or 'thin'"
},
"enrichment_pipeline": {
"additionalProperties": true,
"type": "object",
"title": "Enrichment Pipeline",
"description": "Enrichment pipeline configuration"
},
"is_active": {
"type": "boolean",
"title": "Is Active",
"description": "Whether inbox accepts new items"
},
"item_count": {
"type": "integer",
"minimum": 0.0,
"title": "Item Count",
"description": "Number of items in the inbox",
"default": 0
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At",
"description": "When the inbox was created"
},
"updated_at": {
"type": "string",
"format": "date-time",
"title": "Updated At",
"description": "When the inbox was last updated"
}
},
"type": "object",
"required": [
"id",
"name",
"owner_type",
"owner_id",
"email_enabled",
"api_enabled",
"webhook_configured",
"payload_mode",
"is_active",
"created_at",
"updated_at"
],
"title": "InboxResponse",
"description": "Inbox details response.\n\nNote: webhook_secret is never returned for security."
}
Response 400 Bad Request
Response 401 Unauthorized
Response 402 Payment Required
Response 403 Forbidden
Response 404 Not Found
Response 422 Unprocessable Content
GET /v1/inboxes¶
List inboxes
Description
List all inboxes in the authenticated tenant.
Required permission: inbox:read
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
limit |
query | integer | 100 | No | |
offset |
query | integer | 0 | No | |
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Response 200 OK
{
"inboxes": [
{
"id": "ce9f368a-8b69-4390-902e-e88e13fd002a",
"name": "string",
"description": null,
"owner_type": "string",
"owner_id": "8d6e1d68-f2e0-46d6-bcd6-e9a63858b4b5",
"owner_name": null,
"owner_email": null,
"email_enabled": true,
"email_address": null,
"api_enabled": true,
"allowed_senders": [
"string"
],
"allowed_domains": [
"string"
],
"webhook_url": null,
"webhook_configured": true,
"payload_mode": "string",
"enrichment_pipeline": {},
"is_active": true,
"item_count": 0,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z"
}
],
"total": 0
}
Schema of the response body
{
"properties": {
"inboxes": {
"items": {
"$ref": "#/components/schemas/InboxResponse"
},
"type": "array",
"title": "Inboxes",
"description": "List of inboxes"
},
"total": {
"type": "integer",
"minimum": 0.0,
"title": "Total",
"description": "Total number of inboxes"
}
},
"type": "object",
"required": [
"inboxes",
"total"
],
"title": "InboxListResponse",
"description": "Response for listing inboxes."
}
Response 401 Unauthorized
Response 403 Forbidden
Response 422 Unprocessable Content
GET /v1/inboxes/suggest-email¶
Suggest email local part
Description
Return one memorable local part (e.g. calm-leaf-a3k9x) for pre-filling the inbox email field. No persistence or collision check. Caller appends @domain.
Required permission: inbox:create
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Response 200 OK
Schema of the response body
{
"properties": {
"local_part": {
"type": "string",
"title": "Local Part",
"description": "Memorable local part (e.g. calm-leaf-a3k9x). Caller appends @domain."
}
},
"type": "object",
"required": [
"local_part"
],
"title": "SuggestEmailResponse",
"description": "Response for suggest-email endpoint: one memorable local part for pre-filling."
}
Response 401 Unauthorized
Response 403 Forbidden
Response 422 Unprocessable Content
GET /v1/inboxes/{inbox_id}¶
Get inbox
Description
Get details of a specific inbox.
Required permission: inbox:read
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
inbox_id |
path | string | No | ||
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Response 200 OK
{
"id": "ff0d5fc2-a5e1-4889-bb47-3da789739aeb",
"name": "string",
"description": null,
"owner_type": "string",
"owner_id": "18937598-f136-4442-8df5-80c5168e5f99",
"owner_name": null,
"owner_email": null,
"email_enabled": true,
"email_address": null,
"api_enabled": true,
"allowed_senders": [
"string"
],
"allowed_domains": [
"string"
],
"webhook_url": null,
"webhook_configured": true,
"payload_mode": "string",
"enrichment_pipeline": {},
"is_active": true,
"item_count": 0,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z"
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id",
"description": "Unique inbox identifier"
},
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"description": "Inbox description"
},
"owner_type": {
"type": "string",
"title": "Owner Type",
"description": "Owner type: 'user' or 'organization'"
},
"owner_id": {
"type": "string",
"format": "uuid",
"title": "Owner Id",
"description": "Owner ID"
},
"owner_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Owner Name",
"description": "Owner's display name"
},
"owner_email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Owner Email",
"description": "Owner's email (for users)"
},
"email_enabled": {
"type": "boolean",
"title": "Email Enabled",
"description": "Whether email receiving is enabled"
},
"email_address": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Email Address",
"description": "Email address for receiving (if enabled)"
},
"api_enabled": {
"type": "boolean",
"title": "Api Enabled",
"description": "Whether API receiving is enabled"
},
"allowed_senders": {
"items": {
"type": "string"
},
"type": "array",
"title": "Allowed Senders",
"description": "Allowed sender emails"
},
"allowed_domains": {
"items": {
"type": "string"
},
"type": "array",
"title": "Allowed Domains",
"description": "Allowed sender domains"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Webhook Url",
"description": "Webhook URL for delivery"
},
"webhook_configured": {
"type": "boolean",
"title": "Webhook Configured",
"description": "Whether webhook is configured"
},
"payload_mode": {
"type": "string",
"title": "Payload Mode",
"description": "Webhook payload mode: 'full' or 'thin'"
},
"enrichment_pipeline": {
"additionalProperties": true,
"type": "object",
"title": "Enrichment Pipeline",
"description": "Enrichment pipeline configuration"
},
"is_active": {
"type": "boolean",
"title": "Is Active",
"description": "Whether inbox accepts new items"
},
"item_count": {
"type": "integer",
"minimum": 0.0,
"title": "Item Count",
"description": "Number of items in the inbox",
"default": 0
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At",
"description": "When the inbox was created"
},
"updated_at": {
"type": "string",
"format": "date-time",
"title": "Updated At",
"description": "When the inbox was last updated"
}
},
"type": "object",
"required": [
"id",
"name",
"owner_type",
"owner_id",
"email_enabled",
"api_enabled",
"webhook_configured",
"payload_mode",
"is_active",
"created_at",
"updated_at"
],
"title": "InboxResponse",
"description": "Inbox details response.\n\nNote: webhook_secret is never returned for security."
}
Response 401 Unauthorized
Response 403 Forbidden
Response 404 Not Found
Response 422 Unprocessable Content
PATCH /v1/inboxes/{inbox_id}¶
Update inbox
Description
Update an inbox's configuration.
Only the fields provided will be updated. All fields are optional.
Required permission: inbox:write
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
inbox_id |
path | string | No | ||
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Request body
{
"name": null,
"description": null,
"webhook_url": null,
"webhook_secret": null,
"is_active": null,
"allowed_senders": null,
"allowed_domains": null,
"payload_mode": null,
"email_enabled": null,
"email_prefix": null,
"enrichment_pipeline": null
}
Schema of the request body
{
"properties": {
"name": {
"anyOf": [
{
"type": "string",
"maxLength": 255,
"minLength": 1
},
{
"type": "null"
}
],
"title": "Name",
"description": "Human-readable name for the inbox"
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 1000
},
{
"type": "null"
}
],
"title": "Description",
"description": "Description of the inbox purpose"
},
"webhook_url": {
"anyOf": [
{
"type": "string",
"maxLength": 2048
},
{
"type": "null"
}
],
"title": "Webhook Url",
"description": "Webhook URL for delivery notifications"
},
"webhook_secret": {
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
],
"title": "Webhook Secret",
"description": "Secret for signing webhook payloads"
},
"is_active": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is Active",
"description": "Whether the inbox accepts new items"
},
"allowed_senders": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Allowed Senders",
"description": "List of allowed sender email addresses",
"examples": [
[
"trusted@example.com",
"partner@company.com"
]
]
},
"allowed_domains": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Allowed Domains",
"description": "List of allowed sender domains",
"examples": [
[
"example.com",
"company.com"
]
]
},
"payload_mode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Payload Mode",
"description": "Webhook payload mode: 'full' or 'thin'",
"examples": [
"full",
"thin"
]
},
"email_enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Email Enabled",
"description": "Whether email receiving is enabled for this inbox"
},
"email_prefix": {
"anyOf": [
{
"type": "string",
"maxLength": 64,
"pattern": "^[a-z0-9]([a-z0-9\\-]*[a-z0-9])?$"
},
{
"type": "null"
}
],
"title": "Email Prefix",
"description": "Email prefix (part before @). Backend constructs full address.",
"examples": [
"support",
"invoices"
]
},
"enrichment_pipeline": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Enrichment Pipeline",
"description": "Enrichment pipeline configuration. Set enabled=true with steps to activate.",
"examples": [
{
"enabled": true,
"steps": [
{
"enabled": true,
"slug": "text_extract"
}
]
}
]
}
},
"type": "object",
"title": "UpdateInboxRequest",
"description": "Request body for updating an inbox. All fields are optional."
}
Response 200 OK
{
"id": "698f4f9d-22c9-467d-8068-4aafb3f6b2f7",
"name": "string",
"description": null,
"owner_type": "string",
"owner_id": "0e375071-bda4-4e75-b7c1-d5ec9f725cdf",
"owner_name": null,
"owner_email": null,
"email_enabled": true,
"email_address": null,
"api_enabled": true,
"allowed_senders": [
"string"
],
"allowed_domains": [
"string"
],
"webhook_url": null,
"webhook_configured": true,
"payload_mode": "string",
"enrichment_pipeline": {},
"is_active": true,
"item_count": 0,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z"
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id",
"description": "Unique inbox identifier"
},
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"description": "Inbox description"
},
"owner_type": {
"type": "string",
"title": "Owner Type",
"description": "Owner type: 'user' or 'organization'"
},
"owner_id": {
"type": "string",
"format": "uuid",
"title": "Owner Id",
"description": "Owner ID"
},
"owner_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Owner Name",
"description": "Owner's display name"
},
"owner_email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Owner Email",
"description": "Owner's email (for users)"
},
"email_enabled": {
"type": "boolean",
"title": "Email Enabled",
"description": "Whether email receiving is enabled"
},
"email_address": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Email Address",
"description": "Email address for receiving (if enabled)"
},
"api_enabled": {
"type": "boolean",
"title": "Api Enabled",
"description": "Whether API receiving is enabled"
},
"allowed_senders": {
"items": {
"type": "string"
},
"type": "array",
"title": "Allowed Senders",
"description": "Allowed sender emails"
},
"allowed_domains": {
"items": {
"type": "string"
},
"type": "array",
"title": "Allowed Domains",
"description": "Allowed sender domains"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Webhook Url",
"description": "Webhook URL for delivery"
},
"webhook_configured": {
"type": "boolean",
"title": "Webhook Configured",
"description": "Whether webhook is configured"
},
"payload_mode": {
"type": "string",
"title": "Payload Mode",
"description": "Webhook payload mode: 'full' or 'thin'"
},
"enrichment_pipeline": {
"additionalProperties": true,
"type": "object",
"title": "Enrichment Pipeline",
"description": "Enrichment pipeline configuration"
},
"is_active": {
"type": "boolean",
"title": "Is Active",
"description": "Whether inbox accepts new items"
},
"item_count": {
"type": "integer",
"minimum": 0.0,
"title": "Item Count",
"description": "Number of items in the inbox",
"default": 0
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At",
"description": "When the inbox was created"
},
"updated_at": {
"type": "string",
"format": "date-time",
"title": "Updated At",
"description": "When the inbox was last updated"
}
},
"type": "object",
"required": [
"id",
"name",
"owner_type",
"owner_id",
"email_enabled",
"api_enabled",
"webhook_configured",
"payload_mode",
"is_active",
"created_at",
"updated_at"
],
"title": "InboxResponse",
"description": "Inbox details response.\n\nNote: webhook_secret is never returned for security."
}
Response 400 Bad Request
Response 401 Unauthorized
Response 403 Forbidden
Response 404 Not Found
Response 422 Unprocessable Content
DELETE /v1/inboxes/{inbox_id}¶
Delete inbox
Description
Delete an inbox.
Warning: This is a permanent deletion. All items in the inbox will also be deleted.
Required permission: inbox:delete
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
inbox_id |
path | string | No | ||
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Response 204 No Content
Response 401 Unauthorized
Response 403 Forbidden
Response 404 Not Found
Response 422 Unprocessable Content
POST /v1/inboxes/{inbox_id}/items¶
Create Item
Description
Submit content to an inbox.
Accepts multipart/form-data with a file and metadata fields. The raw content is stored durably and an ITEM_RECEIVED event is staged.
Deduplication: If a provider_message_id matches an existing item,
or if the content hash matches, the existing item is returned with
is_duplicate: true.
Authorization: Basic sender authorization is checked against the
inbox's allowed_senders and allowed_domains configuration.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
inbox_id |
path | string | No | ||
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Request body
{
"file": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ=",
"sender_address": "string",
"sender_display_name": null,
"subject": null,
"provider_message_id": null
}
Schema of the request body
{
"properties": {
"file": {
"type": "string",
"format": "binary",
"title": "File",
"description": "Raw content to ingest"
},
"sender_address": {
"type": "string",
"title": "Sender Address",
"description": "Sender's email address"
},
"sender_display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Sender Display Name",
"description": "Sender's display name"
},
"subject": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Subject",
"description": "Subject line"
},
"provider_message_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Provider Message Id",
"description": "Provider's message ID for deduplication"
}
},
"type": "object",
"required": [
"file",
"sender_address"
],
"title": "Body_create_item_v1_inboxes__inbox_id__items_post"
}
Response 201 Created
{
"id": "216e14f4-72c4-4d07-b729-5ba5e3bb63a2",
"inbox_id": "6096cf97-470f-4d90-a770-3f588e5383a0",
"inbound_channel": "string",
"status": "string",
"content_type": "string",
"size_bytes": 0,
"dedupe_key": "string",
"is_duplicate": true,
"created_at": "2022-04-13T15:42:05.901Z"
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id",
"description": "Unique item identifier"
},
"inbox_id": {
"type": "string",
"format": "uuid",
"title": "Inbox Id",
"description": "Inbox that received the item"
},
"inbound_channel": {
"type": "string",
"title": "Inbound Channel",
"description": "Inbound channel that received the item"
},
"status": {
"type": "string",
"title": "Status",
"description": "Current item status",
"examples": [
"received"
]
},
"content_type": {
"type": "string",
"title": "Content Type",
"description": "MIME type of the content"
},
"size_bytes": {
"type": "integer",
"minimum": 0.0,
"title": "Size Bytes",
"description": "Size of raw content in bytes"
},
"dedupe_key": {
"type": "string",
"title": "Dedupe Key",
"description": "Deduplication key"
},
"is_duplicate": {
"type": "boolean",
"title": "Is Duplicate",
"description": "True if this is a duplicate submission (returns existing item)"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At",
"description": "When the item was created"
}
},
"type": "object",
"required": [
"id",
"inbox_id",
"inbound_channel",
"status",
"content_type",
"size_bytes",
"dedupe_key",
"is_duplicate",
"created_at"
],
"title": "CreateItemResponse",
"description": "Response after successfully creating an item."
}
Response 400 Bad Request
Schema of the response body
{
"properties": {
"error": {
"type": "string",
"title": "Error",
"description": "Error code"
},
"message": {
"type": "string",
"title": "Message",
"description": "Human-readable error message"
},
"details": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Details",
"description": "Additional error details"
},
"request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Request Id",
"description": "Request ID for tracing"
}
},
"type": "object",
"required": [
"error",
"message"
],
"title": "ErrorResponse",
"description": "Standard error response."
}
Response 402 Payment Required
Schema of the response body
{
"properties": {
"error": {
"type": "string",
"title": "Error",
"description": "Error code"
},
"message": {
"type": "string",
"title": "Message",
"description": "Human-readable error message"
},
"details": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Details",
"description": "Additional error details"
},
"request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Request Id",
"description": "Request ID for tracing"
}
},
"type": "object",
"required": [
"error",
"message"
],
"title": "ErrorResponse",
"description": "Standard error response."
}
Response 403 Forbidden
Schema of the response body
{
"properties": {
"error": {
"type": "string",
"title": "Error",
"description": "Error code"
},
"message": {
"type": "string",
"title": "Message",
"description": "Human-readable error message"
},
"details": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Details",
"description": "Additional error details"
},
"request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Request Id",
"description": "Request ID for tracing"
}
},
"type": "object",
"required": [
"error",
"message"
],
"title": "ErrorResponse",
"description": "Standard error response."
}
Response 404 Not Found
Schema of the response body
{
"properties": {
"error": {
"type": "string",
"title": "Error",
"description": "Error code"
},
"message": {
"type": "string",
"title": "Message",
"description": "Human-readable error message"
},
"details": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Details",
"description": "Additional error details"
},
"request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Request Id",
"description": "Request ID for tracing"
}
},
"type": "object",
"required": [
"error",
"message"
],
"title": "ErrorResponse",
"description": "Standard error response."
}
Response 413 Content Too Large
Schema of the response body
{
"properties": {
"error": {
"type": "string",
"title": "Error",
"description": "Error code"
},
"message": {
"type": "string",
"title": "Message",
"description": "Human-readable error message"
},
"details": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Details",
"description": "Additional error details"
},
"request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Request Id",
"description": "Request ID for tracing"
}
},
"type": "object",
"required": [
"error",
"message"
],
"title": "ErrorResponse",
"description": "Standard error response."
}
Response 422 Unprocessable Content
Schema of the response body
{
"properties": {
"error": {
"type": "string",
"title": "Error",
"description": "Error code"
},
"message": {
"type": "string",
"title": "Message",
"description": "Human-readable error message"
},
"details": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Details",
"description": "Additional error details"
},
"request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Request Id",
"description": "Request ID for tracing"
}
},
"type": "object",
"required": [
"error",
"message"
],
"title": "ErrorResponse",
"description": "Standard error response."
}
GET /v1/inboxes/{inbox_id}/items¶
List items in inbox
Description
List all items in a specific inbox with pagination.
Required permission: item:read
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
inbox_id |
path | string | No | ||
limit |
query | integer | 100 | No | |
offset |
query | integer | 0 | No | |
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Response 200 OK
{
"items": [
{
"id": "59b1d639-339e-43c2-b619-b2b028a8282c",
"inbox_id": "59f5d687-9a35-4eba-97f6-c1668540e550",
"inbound_channel": "string",
"status": "string",
"content_type": "string",
"size_bytes": 0,
"sender_address": "string",
"sender_display_name": null,
"sender_domain": "string",
"subject": null,
"dedupe_key": "string",
"auth_decision": "string",
"auth_reasons": [
"string"
],
"received_at": "2022-04-13T15:42:05.901Z",
"normalized_at": null,
"ready_at": null,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z",
"metadata": {}
}
],
"total": 0
}
Schema of the response body
{
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/ItemResponse"
},
"type": "array",
"title": "Items",
"description": "List of items"
},
"total": {
"type": "integer",
"minimum": 0.0,
"title": "Total",
"description": "Total number of items in the inbox"
}
},
"type": "object",
"required": [
"items",
"total"
],
"title": "ItemListResponse",
"description": "Response for listing items."
}
Response 401 Unauthorized
Response 403 Forbidden
Response 404 Not Found
Schema of the response body
{
"properties": {
"error": {
"type": "string",
"title": "Error",
"description": "Error code"
},
"message": {
"type": "string",
"title": "Message",
"description": "Human-readable error message"
},
"details": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Details",
"description": "Additional error details"
},
"request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Request Id",
"description": "Request ID for tracing"
}
},
"type": "object",
"required": [
"error",
"message"
],
"title": "ErrorResponse",
"description": "Standard error response."
}
Response 422 Unprocessable Content
items¶
GET /v1/items/{item_id}¶
Get item
Description
Get details of a specific item.
Required permission: item:read
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
item_id |
path | string | No | ||
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Response 200 OK
{
"id": "0a45d8ef-6281-4134-8747-e95b87b6f98b",
"inbox_id": "03a5e492-532e-4aec-8ad3-29f658f9fb2a",
"inbound_channel": "string",
"status": "string",
"content_type": "string",
"size_bytes": 0,
"sender_address": "string",
"sender_display_name": null,
"sender_domain": "string",
"subject": null,
"dedupe_key": "string",
"auth_decision": "string",
"auth_reasons": [
"string"
],
"received_at": "2022-04-13T15:42:05.901Z",
"normalized_at": null,
"ready_at": null,
"created_at": "2022-04-13T15:42:05.901Z",
"updated_at": "2022-04-13T15:42:05.901Z",
"metadata": {}
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"inbox_id": {
"type": "string",
"format": "uuid",
"title": "Inbox Id"
},
"inbound_channel": {
"type": "string",
"title": "Inbound Channel"
},
"status": {
"type": "string",
"title": "Status"
},
"content_type": {
"type": "string",
"title": "Content Type"
},
"size_bytes": {
"type": "integer",
"title": "Size Bytes"
},
"sender_address": {
"type": "string",
"title": "Sender Address"
},
"sender_display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Sender Display Name"
},
"sender_domain": {
"type": "string",
"title": "Sender Domain"
},
"subject": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Subject"
},
"dedupe_key": {
"type": "string",
"title": "Dedupe Key"
},
"auth_decision": {
"type": "string",
"title": "Auth Decision"
},
"auth_reasons": {
"items": {
"type": "string"
},
"type": "array",
"title": "Auth Reasons"
},
"received_at": {
"type": "string",
"format": "date-time",
"title": "Received At"
},
"normalized_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Normalized At"
},
"ready_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Ready At"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"updated_at": {
"type": "string",
"format": "date-time",
"title": "Updated At"
},
"metadata": {
"additionalProperties": true,
"type": "object",
"title": "Metadata"
}
},
"type": "object",
"required": [
"id",
"inbox_id",
"inbound_channel",
"status",
"content_type",
"size_bytes",
"sender_address",
"sender_domain",
"dedupe_key",
"auth_decision",
"received_at",
"created_at",
"updated_at"
],
"title": "ItemResponse",
"description": "Full item details response."
}
Response 401 Unauthorized
Response 403 Forbidden
Response 404 Not Found
Schema of the response body
{
"properties": {
"error": {
"type": "string",
"title": "Error",
"description": "Error code"
},
"message": {
"type": "string",
"title": "Message",
"description": "Human-readable error message"
},
"details": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Details",
"description": "Additional error details"
},
"request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Request Id",
"description": "Request ID for tracing"
}
},
"type": "object",
"required": [
"error",
"message"
],
"title": "ErrorResponse",
"description": "Standard error response."
}
Response 422 Unprocessable Content
GET /v1/items/{item_id}/deliveries¶
Get item deliveries
Description
Get all delivery attempts for a specific item.
Required permission: item:read
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
item_id |
path | string | No | ||
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Response 200 OK
{
"deliveries": [
{
"id": "93b1cc2c-4b1b-4f29-97d5-a494882a1be2",
"item_id": "17a48d34-3643-4cc9-8a20-ed83579ee3b1",
"webhook_url": "string",
"status": "string",
"attempt_count": 0,
"max_attempts": 0,
"last_error": null,
"succeeded_at": null,
"failed_at": null,
"created_at": "2022-04-13T15:42:05.901Z",
"attempts": [
{
"id": "021cd9cc-c587-480f-a198-b204b48111e0",
"attempt_number": 0,
"status_code": null,
"response_body": null,
"error_message": null,
"started_at": "2022-04-13T15:42:05.901Z",
"completed_at": null,
"duration_ms": null
}
]
}
]
}
Schema of the response body
{
"properties": {
"deliveries": {
"items": {
"$ref": "#/components/schemas/DeliveryResponse"
},
"type": "array",
"title": "Deliveries",
"description": "List of deliveries for the item"
}
},
"type": "object",
"required": [
"deliveries"
],
"title": "ItemDeliveriesResponse",
"description": "Response for listing deliveries for an item."
}
Response 401 Unauthorized
Response 403 Forbidden
Response 404 Not Found
Schema of the response body
{
"properties": {
"error": {
"type": "string",
"title": "Error",
"description": "Error code"
},
"message": {
"type": "string",
"title": "Message",
"description": "Human-readable error message"
},
"details": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Details",
"description": "Additional error details"
},
"request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Request Id",
"description": "Request ID for tracing"
}
},
"type": "object",
"required": [
"error",
"message"
],
"title": "ErrorResponse",
"description": "Standard error response."
}
Response 422 Unprocessable Content
GET /v1/items/{item_id}/attachments¶
Get item attachments
Description
Get all attachments for a specific item with presigned download URLs.
Required permission: item:read
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
item_id |
path | string | No | ||
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Response 200 OK
{
"attachments": [
{
"id": "4bf3f2ac-6840-407f-9a59-cd5d0c5058a9",
"filename": "string",
"content_type": "string",
"size_bytes": 0,
"download_url": null,
"content_id": null,
"created_at": "2022-04-13T15:42:05.901Z"
}
]
}
Schema of the response body
{
"properties": {
"attachments": {
"items": {
"$ref": "#/components/schemas/AttachmentResponse"
},
"type": "array",
"title": "Attachments",
"description": "List of attachments for the item"
}
},
"type": "object",
"required": [
"attachments"
],
"title": "ItemAttachmentsResponse",
"description": "Response for listing attachments for an item."
}
Response 401 Unauthorized
Response 403 Forbidden
Response 404 Not Found
Schema of the response body
{
"properties": {
"error": {
"type": "string",
"title": "Error",
"description": "Error code"
},
"message": {
"type": "string",
"title": "Message",
"description": "Human-readable error message"
},
"details": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Details",
"description": "Additional error details"
},
"request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Request Id",
"description": "Request ID for tracing"
}
},
"type": "object",
"required": [
"error",
"message"
],
"title": "ErrorResponse",
"description": "Standard error response."
}
Response 422 Unprocessable Content
GET /v1/items/{item_id}/webhook-payload-preview¶
Get webhook payload preview
Description
Preview the JSON payload that would be sent (or was sent) for this item's webhook.
Matches the webhook payload schema (contracts/webhook_payload.schema.json). Uses the inbox's configured payload_mode (full or thin).
Required permission: item:read
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
item_id |
path | string | No | ||
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Response 200 OK
Response 401 Unauthorized
Response 403 Forbidden
Response 404 Not Found
Schema of the response body
{
"properties": {
"error": {
"type": "string",
"title": "Error",
"description": "Error code"
},
"message": {
"type": "string",
"title": "Message",
"description": "Human-readable error message"
},
"details": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Details",
"description": "Additional error details"
},
"request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Request Id",
"description": "Request ID for tracing"
}
},
"type": "object",
"required": [
"error",
"message"
],
"title": "ErrorResponse",
"description": "Standard error response."
}
Response 422 Unprocessable Content
api-keys¶
POST /v1/api-keys¶
Create API key
Description
Create a new API key for the authenticated tenant.
WARNING: The full API key is only returned in this response. Store it securely - it cannot be retrieved again.
Required permission: api_key:create
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Request body
Schema of the request body
{
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"title": "Name",
"description": "Human-readable name for the API key",
"examples": [
"Production API Key",
"CI/CD Pipeline Key"
]
},
"scopes": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Scopes",
"description": "Optional scope restrictions. If empty, key has all permissions.",
"examples": [
[
"inbox:read",
"item:submit"
]
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Expires At",
"description": "Optional expiration time. If not set, key never expires."
}
},
"type": "object",
"required": [
"name"
],
"title": "CreateApiKeyRequest",
"description": "Request body for creating an API key."
}
Response 201 Created
{
"id": "e240e6e0-57e8-4592-82e1-28c7dfbff5ea",
"key": "string",
"key_prefix": "string",
"name": "string",
"scopes": [
"string"
],
"expires_at": null,
"created_at": "2022-04-13T15:42:05.901Z"
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id",
"description": "Unique API key identifier"
},
"key": {
"type": "string",
"title": "Key",
"description": "Full API key. WARNING: Only returned once at creation. Store securely!",
"examples": [
"sk_live_dGhpcyBpcyBhIHRlc3Qga2V5"
]
},
"key_prefix": {
"type": "string",
"title": "Key Prefix",
"description": "Key prefix for identification in logs/UI",
"examples": [
"sk_live_XXXXXXXX"
]
},
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable name"
},
"scopes": {
"items": {
"type": "string"
},
"type": "array",
"title": "Scopes",
"description": "Scope restrictions (empty = all permissions)"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Expires At",
"description": "Expiration time if set"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At",
"description": "When the key was created"
}
},
"type": "object",
"required": [
"id",
"key",
"key_prefix",
"name",
"created_at"
],
"title": "CreateApiKeyResponse",
"description": "Response after creating an API key.\n\nWARNING: The `key` field contains the full API key and is only\nreturned in this response. Store it securely - it cannot be retrieved again."
}
Response 400 Bad Request
Response 401 Unauthorized
Response 403 Forbidden
Response 429 Too Many Requests
Response 422 Unprocessable Content
GET /v1/api-keys¶
List API keys
Description
List all API keys for the authenticated tenant.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
include_revoked |
query | boolean | False | No | |
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Response 200 OK
{
"keys": [
{
"id": "ad191964-5010-40a8-a0e7-4b72ad19a4af",
"key_prefix": "string",
"name": "string",
"scopes": [
"string"
],
"status": "string",
"user_id": "2ee76a59-6eda-4cbf-b75c-6d3c02e5f1e5",
"expires_at": null,
"last_used_at": null,
"created_at": "2022-04-13T15:42:05.901Z"
}
],
"total": 0
}
Schema of the response body
{
"properties": {
"keys": {
"items": {
"$ref": "#/components/schemas/ApiKeyResponse"
},
"type": "array",
"title": "Keys",
"description": "List of API keys"
},
"total": {
"type": "integer",
"minimum": 0.0,
"title": "Total",
"description": "Total number of keys"
}
},
"type": "object",
"required": [
"keys",
"total"
],
"title": "ApiKeyListResponse",
"description": "Response for listing API keys."
}
Response 401 Unauthorized
Response 422 Unprocessable Content
DELETE /v1/api-keys/{key_id}¶
Revoke API key
Description
Revoke an API key. This is a soft delete - the key is marked as revoked but not deleted.
Required permission: api_key:revoke
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
key_id |
path | string | No | ||
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Response 204 No Content
Response 401 Unauthorized
Response 403 Forbidden
Response 404 Not Found
Response 409 Conflict
Response 422 Unprocessable Content
tenant-settings¶
GET /v1/tenant¶
Get current tenant
Description
Returns the current tenant (from auth context). Requires platform admin or tenant owner/admin.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Response 200 OK
{
"id": "266d2ab3-f9c1-4cbd-a8fd-959c2aa307a9",
"slug": "string",
"name": "string",
"plan": "string"
}
Schema of the response body
{
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id",
"description": "Tenant UUID"
},
"slug": {
"type": "string",
"title": "Slug",
"description": "URL-safe tenant identifier"
},
"name": {
"type": "string",
"title": "Name",
"description": "Tenant display name"
},
"plan": {
"type": "string",
"title": "Plan",
"description": "Plan key: free, developer, pro, internal"
}
},
"type": "object",
"required": [
"id",
"slug",
"name",
"plan"
],
"title": "CurrentTenantResponse",
"description": "Current tenant summary for settings/billing display."
}
Response 401 Unauthorized
Response 403 Forbidden
Response 422 Unprocessable Content
GET /v1/tenant/usage¶
Get tenant usage
Description
Returns usage for the current period and plan limits. Requires platform admin or tenant owner/admin.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Response 200 OK
{
"period_start": "2022-04-13T15:42:05.901Z",
"inbox_count": 0,
"item_count": 0,
"enrichment_count": 0,
"limits": {
"max_inboxes": 0,
"items_per_month": 0,
"enrichment_available": true,
"enrichment_items_per_month": null
}
}
Schema of the response body
{
"properties": {
"period_start": {
"type": "string",
"format": "date-time",
"title": "Period Start",
"description": "Start of current usage period (e.g. first of month UTC)"
},
"inbox_count": {
"type": "integer",
"minimum": 0.0,
"title": "Inbox Count"
},
"item_count": {
"type": "integer",
"minimum": 0.0,
"title": "Item Count"
},
"enrichment_count": {
"type": "integer",
"minimum": 0.0,
"title": "Enrichment Count"
},
"limits": {
"$ref": "#/components/schemas/UsageLimitsResponse",
"description": "Plan limits for this tenant"
}
},
"type": "object",
"required": [
"period_start",
"inbox_count",
"item_count",
"enrichment_count",
"limits"
],
"title": "TenantUsageResponse",
"description": "Current usage and limits for the tenant's plan."
}
Response 401 Unauthorized
Response 403 Forbidden
Response 422 Unprocessable Content
GET /v1/tenant/members¶
List tenant members
Description
Returns all users in the current tenant with their roles. Requires platform admin or tenant owner/admin.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
HTTPBearer |
header | string | N/A | No | JWT Bearer token |
X-API-Key |
header | None | No | ||
X-Tenant-ID |
header | None | No |
Response 200 OK
{
"members": [
{
"user_id": "abe9fa48-314d-4b47-ad48-f63b50933b85",
"email": null,
"name": null,
"role": "string",
"joined_at": "2022-04-13T15:42:05.901Z"
}
],
"total": 0
}
Schema of the response body
{
"properties": {
"members": {
"items": {
"$ref": "#/components/schemas/TenantMemberSummary"
},
"type": "array",
"title": "Members",
"description": "Tenant members"
},
"total": {
"type": "integer",
"minimum": 0.0,
"title": "Total",
"description": "Total count"
}
},
"type": "object",
"required": [
"members",
"total"
],
"title": "TenantMembersResponse",
"description": "List of tenant members."
}
Response 401 Unauthorized
Response 403 Forbidden
Response 422 Unprocessable Content
webhooks¶
POST /v1/webhooks/stripe¶
Stripe webhook
Description
Receive Stripe subscription events. Configure webhook secret via SEMA_STRIPE__WEBHOOK_SECRET.
Response 200 OK
Schemas¶
ApiKeyListResponse¶
| Name | Type |
|---|---|
keys |
Array<ApiKeyResponse> |
total |
integer |
ApiKeyResponse¶
| Name | Type |
|---|---|
created_at |
string(date-time) |
expires_at |
|
id |
string(uuid) |
key_prefix |
string |
last_used_at |
|
name |
string |
scopes |
Array<string> |
status |
string |
user_id |
string(uuid) |
AttachmentResponse¶
| Name | Type |
|---|---|
content_id |
|
content_type |
string |
created_at |
string(date-time) |
download_url |
|
filename |
string |
id |
string(uuid) |
size_bytes |
integer |
Body_create_item_v1_inboxes__inbox_id__items_post¶
| Name | Type |
|---|---|
file |
string(binary) |
provider_message_id |
|
sender_address |
string |
sender_display_name |
|
subject |
CreateApiKeyRequest¶
| Name | Type |
|---|---|
expires_at |
|
name |
string |
scopes |
CreateApiKeyResponse¶
| Name | Type |
|---|---|
created_at |
string(date-time) |
expires_at |
|
id |
string(uuid) |
key |
string |
key_prefix |
string |
name |
string |
scopes |
Array<string> |
CreateInboxRequest¶
| Name | Type |
|---|---|
description |
|
email_enabled |
boolean |
email_prefix |
|
name |
string |
owner_id |
|
owner_type |
|
webhook_secret |
|
webhook_url |
CreateItemResponse¶
| Name | Type |
|---|---|
content_type |
string |
created_at |
string(date-time) |
dedupe_key |
string |
id |
string(uuid) |
inbound_channel |
string |
inbox_id |
string(uuid) |
is_duplicate |
boolean |
size_bytes |
integer |
status |
string |
CurrentTenantResponse¶
| Name | Type |
|---|---|
id |
string(uuid) |
name |
string |
plan |
string |
slug |
string |
DeliveryAttemptResponse¶
| Name | Type |
|---|---|
attempt_number |
integer |
completed_at |
|
duration_ms |
|
error_message |
|
id |
string(uuid) |
response_body |
|
started_at |
string(date-time) |
status_code |
DeliveryResponse¶
| Name | Type |
|---|---|
attempt_count |
integer |
attempts |
Array<DeliveryAttemptResponse> |
created_at |
string(date-time) |
failed_at |
|
id |
string(uuid) |
item_id |
string(uuid) |
last_error |
|
max_attempts |
integer |
status |
string |
succeeded_at |
|
webhook_url |
string |
ErrorResponse¶
| Name | Type |
|---|---|
details |
|
error |
string |
message |
string |
request_id |
HTTPValidationError¶
| Name | Type |
|---|---|
detail |
Array<ValidationError> |
InboxListResponse¶
| Name | Type |
|---|---|
inboxes |
Array<InboxResponse> |
total |
integer |
InboxResponse¶
| Name | Type |
|---|---|
allowed_domains |
Array<string> |
allowed_senders |
Array<string> |
api_enabled |
boolean |
created_at |
string(date-time) |
description |
|
email_address |
|
email_enabled |
boolean |
enrichment_pipeline |
|
id |
string(uuid) |
is_active |
boolean |
item_count |
integer |
name |
string |
owner_email |
|
owner_id |
string(uuid) |
owner_name |
|
owner_type |
string |
payload_mode |
string |
updated_at |
string(date-time) |
webhook_configured |
boolean |
webhook_url |
ItemAttachmentsResponse¶
| Name | Type |
|---|---|
attachments |
Array<AttachmentResponse> |
ItemDeliveriesResponse¶
| Name | Type |
|---|---|
deliveries |
Array<DeliveryResponse> |
ItemListResponse¶
| Name | Type |
|---|---|
items |
Array<ItemResponse> |
total |
integer |
ItemResponse¶
| Name | Type |
|---|---|
auth_decision |
string |
auth_reasons |
Array<string> |
content_type |
string |
created_at |
string(date-time) |
dedupe_key |
string |
id |
string(uuid) |
inbound_channel |
string |
inbox_id |
string(uuid) |
metadata |
|
normalized_at |
|
ready_at |
|
received_at |
string(date-time) |
sender_address |
string |
sender_display_name |
|
sender_domain |
string |
size_bytes |
integer |
status |
string |
subject |
|
updated_at |
string(date-time) |
SuggestEmailResponse¶
| Name | Type |
|---|---|
local_part |
string |
TenantMembersResponse¶
| Name | Type |
|---|---|
members |
Array<TenantMemberSummary> |
total |
integer |
TenantMemberSummary¶
| Name | Type |
|---|---|
email |
|
joined_at |
string(date-time) |
name |
|
role |
string |
user_id |
string(uuid) |
TenantUsageResponse¶
| Name | Type |
|---|---|
enrichment_count |
integer |
inbox_count |
integer |
item_count |
integer |
limits |
UsageLimitsResponse |
period_start |
string(date-time) |
UpdateInboxRequest¶
| Name | Type |
|---|---|
allowed_domains |
|
allowed_senders |
|
description |
|
email_enabled |
|
email_prefix |
|
enrichment_pipeline |
|
is_active |
|
name |
|
payload_mode |
|
webhook_secret |
|
webhook_url |
UsageLimitsResponse¶
| Name | Type |
|---|---|
enrichment_available |
boolean |
enrichment_items_per_month |
|
items_per_month |
integer |
max_inboxes |
integer |
ValidationError¶
| Name | Type |
|---|---|
loc |
Array<> |
msg |
string |
type |
string |
Security schemes¶
| Name | Type | Scheme | Description |
|---|---|---|---|
| HTTPBearer | http | bearer |