# Sema

> Universal ingestion infrastructure for AI agents.

Sema provides secure Inboxes that accept content (files, emails, API submissions) and deliver normalized events to your systems via webhooks. It handles identity verification, sender authorization, content parsing, and reliable webhook delivery so you can focus on your agent logic.

## Core Concepts

- **Inbox**: A secure intake endpoint with its own inbound channels, allowed senders, and webhook configuration. Each Inbox can receive content from multiple sources and delivers events when content is ready.
- **Item**: A single unit of inbound content received by an Inbox. Items progress through a pipeline: received → normalized → ready → delivered.
- **Delivery**: Webhook delivery to your endpoint when an Item is ready. Sema uses Standard Webhooks signing, automatic retries with exponential backoff, and supports thin or full payload modes.

## Minimal flow

1. Create Inbox: POST /v1/inboxes with name, webhook_url, webhook_secret (whsec_...).
2. Submit Item: POST /v1/inboxes/{inbox_id}/items (multipart: file, sender_address, subject, provider_message_id).
3. Handle webhook: ITEM_READY at your webhook_url; verify with webhook-id + webhook-timestamp + webhook-signature (Standard Webhooks).

## Documentation

- [Home](https://docs.withsema.com/): Overview and getting started pointers
- [Quickstart](https://docs.withsema.com/getting-started/quickstart/): Create an Inbox, submit an Item, receive a webhook
- [Inboxes](https://docs.withsema.com/concepts/inboxes/): Core mental model, lifecycle, sender authorization
- [API Overview](https://docs.withsema.com/api/overview/): Endpoints for Inboxes, Items, API keys, and Organizations
- [Webhooks](https://docs.withsema.com/api/webhooks/): Standard Webhooks headers, signature verification, payload formats, retry behavior
- [OpenAPI spec](https://docs.withsema.com/api/openapi.public.json): Machine-readable API definition

## API Authentication

- API key: `Authorization: Bearer sk_live_...` or `X-API-Key: sk_live_...`
- Env: SEMA_API_KEY, SEMA_BASE_URL (default https://api.withsema.com)
- Tenant context is derived from the API key

## Webhook Event

The primary event is `ITEM_READY`, sent when an Item has been processed and is ready for consumption. The payload includes:

- `schema_version`: "1.0"
- `event_type`: "ITEM_READY"
- `tenant_id`, `inbox_id`, `item_id`
- `inbound_channel`: "api" or "email"
- `payload_mode`: "thin" or "full"
- `deliverable`: Item data (references for thin, full metadata for full)

Verify webhooks using the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers per the Standard Webhooks spec.