# Primitive API

> Primitive is email infrastructure for AI agents. This file maps the Primitive v1 REST API: spec location, auth model, key operations, and error envelope.

## When to use this API

Use the Primitive REST API when an agent needs to:

- Send email and (optionally) wait for the threaded reply without SMTP credentials or DNS setup.
- Read inbound emails, search them, or pull full conversation threads for model context.
- Store durable JSON key-value state across agent turns, retries, emails, and Function invocations with Primitive Memories.
- Manage inbound email addresses, custom domains, webhook endpoints, or hosted JavaScript Functions programmatically.

Do not reach for this API for one-way fire-and-forget notifications when you already have a transactional provider wired up.

## Spec

- OpenAPI 3.1 (JSON): https://www.primitive.dev/openapi.json
- OpenAPI 3.1 (YAML): https://www.primitive.dev/openapi.yaml
- Discovery alias: https://www.primitive.dev/.well-known/openapi.json

## Base URL

- `https://api.primitive.dev/v1`

## Auth

- `Authorization: Bearer prim_<api_key>` or `Authorization: Bearer prim_oat_<oauth_access_token>`
- AS metadata (RFC 8414): https://www.primitive.dev/.well-known/oauth-authorization-server
- Protected Resource metadata (RFC 9728): https://www.primitive.dev/.well-known/oauth-protected-resource
- Walkthrough: https://www.primitive.dev/auth.md

## Operations (overview)

- Send mail: `POST /send-mail` (attachments, reply threading, idempotency hints).
- Receive mail: configured per-domain via webhook or hosted Function endpoint.
- Primitive Memories: `PUT/GET/DELETE /memories` and `GET /memories/search`, operation ids `setMemory`, `getMemory`, `deleteMemory`, and `searchMemories`.
- Manage domains: `GET/POST/DELETE /domains`, `POST /domains/{id}/verify`, `GET /domains/{id}/zone-file`.
- Inbox readiness: `GET /inbox/status`, one consolidated view of domain verification, processing routes, deployed Functions, and recent inbound activity.

## Errors

Shared envelope across the API:

```
{ "error": { "code": "<machine_readable>", "message": "<human>", "request_id": "<id>" } }
```

Common codes: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `rate_limited`, `internal_error`.

## Reference docs

- REST API: https://docs.primitive.dev/docs/api.md
- Primitive Memories: https://docs.primitive.dev/docs/memories.md
- Webhook payload: https://docs.primitive.dev/docs/webhook-payload.md
- Signature verification: https://docs.primitive.dev/docs/signature-verification.md
- SDKs: https://docs.primitive.dev/docs/sdks.md