Base URL¶

Production: https://dev-api.withsema.com. All API endpoints below are prefixed with /v1 (except health checks).

Transport security¶

Use https://dev-api.withsema.com only for production. See Security for HTTPS, API keys, and webhook signing.

Authentication¶

Sema supports:

• API key auth (recommended for service-to-service integrations): create and manage API keys in the dashboard under API keys. Send your key as either:
• Authorization: Bearer <sk_...>

• X-API-Key: <sk_...> Tenant context is derived from the key; X-Tenant-ID is ignored.

• OIDC auth (for user sessions): send Authorization: Bearer <jwt> and include X-Tenant-ID for tenant-scoped endpoints.

Inboxes¶

• POST /v1/inboxes
• GET /v1/inboxes
• GET /v1/inboxes/{inbox_id}
• PATCH /v1/inboxes/{inbox_id}
• DELETE /v1/inboxes/{inbox_id}

Inbox create and update accept optional sender allowlists: allowed_senders (exact email addresses) and allowed_domains. See Concepts → Inboxes.

Items¶

• POST /v1/inboxes/{inbox_id}/items (multipart upload)
• GET /v1/inboxes/{inbox_id}/items
• GET /v1/items/{item_id}
• GET /v1/items/{item_id}/deliveries
• GET /v1/items/{item_id}/attachments

Webhooks¶

Outbound deliveries happen automatically when an inbox has webhook_url configured. See API Reference → Webhooks.

Account / admin¶

API keys¶

• POST /v1/api-keys
• GET /v1/api-keys
• DELETE /v1/api-keys/{key_id}

Invitations¶

• POST /v1/invitations
• GET /v1/invitations
• DELETE /v1/invitations/{invitation_id}
• POST /v1/invitations/{invitation_id}/resend
• GET /v1/me/invitations
• POST /v1/me/invitations/accept

Organizations¶

• POST /v1/organizations
• GET /v1/organizations
• GET /v1/organizations/{organization_id}
• PATCH /v1/organizations/{organization_id}
• DELETE /v1/organizations/{organization_id}
• GET /v1/organizations/{organization_id}/members

Health¶

• GET /health
• GET /health/ready