# 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`.

## Versioning and deprecation

- The API is versioned in the URL path (`/v1`). v1 is never broken in place: deprecated operations and fields are marked `deprecated: true` in the spec, return a `Sunset` response header, and get at least 6 months of notice before removal in a new major version.
- Primitive API deprecation policy: https://docs.primitive.dev/docs/versioning#deprecation-policy

## GraphQL

- [GraphQL API guide](https://docs.primitive.dev/docs/graphql.md): public, read-only endpoint `https://api.primitive.dev/v1/graphql`, introspection enabled, synthetic sample data.
- [GraphQL schema (SDL)](https://api.primitive.dev/graphql.graphql): the authored schema as text, with `@deprecated` annotations.
- [GraphQL versioning and deprecation policy](https://docs.primitive.dev/docs/graphql#versioning-and-deprecation-policy): versioned via `apiVersion` (v1); fields slated for removal carry `@deprecated` with a removal date and keep working until then.

## Reference docs

- Primitive API reference: https://www.primitive.dev/api-reference
- Primitive authentication docs: https://docs.primitive.dev/docs/auth.md
- REST API guide: 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
- Primitive SDKs (TypeScript, Python, Go): https://docs.primitive.dev/docs/sdks.md
- Primitive CLI: https://docs.primitive.dev/docs/cli.md
- Primitive MCP server: https://docs.primitive.dev/docs/connectors.md