# Atoms API

> The canonical API base is https://api.atoms.email/v1. There is no /atoms prefix before /v1.

## Authentication

Private routes use Ed25519 proof-of-possession headers: `Atoms-Key-Id`, `Atoms-Timestamp`, `Atoms-Nonce`, and `Atoms-Signature`. Signatures bind the HTTP method, exact path and query, SHA-256 of the exact body bytes, timestamp, nonce, and key ID.

## Endpoints

- `POST /v1/atoms`: create a paid, task-scoped Atom. Requires an Ed25519 signing key, X25519 encryption key, private-key-derived `address_proof`, TTL, limits, idempotency key, and x402 payment.
- `GET /v1/atoms`: list Atoms accessible to the authenticated signing key.
- `GET /v1/atoms/{atom-ref}`: read current Atom state using the full ID or collision-safe short reference.
- `GET /v1/atoms/{atom-id}/events?after={cursor}&limit={limit}`: resume the immutable event stream.
- `GET /v1/atoms/{atom-id}/messages/{message-id}`: read a sealed-message manifest.
- `GET /v1/atoms/{atom-id}/messages/{message-id}/content`: retrieve HPKE ciphertext for controller-side decryption.
- `POST /v1/atoms/{atom-ref}/messages`: send ordinary email from the Atom and store an HPKE-sealed sent copy.
- `PUT /v1/atoms/{atom-ref}/messages/{message-id}/search-index`: add controller-generated blind tokens for a sealed message.
- `POST /v1/atoms/{atom-ref}/search`: match opaque blind tokens without disclosing the query or correspondence plaintext.
- `POST /v1/atoms/{atom-ref}/renew`: extend an active Atom; signed and x402-paid.
- `POST /v1/atoms/{atom-ref}/reactivate`: restart an expired or archived Atom; signed and x402-paid.
- `POST /v1/atoms/{atom-id}/archive`: stop an Atom from accepting new correspondence.
- `DELETE /v1/atoms/{atom-ref}`: purge the Atom after signed full-ID confirmation.

Atom state includes committed message and ciphertext-byte usage. Message and storage quotas are checked against committed usage, and conditional R2 HEAD updates prevent concurrent receipt or send events from silently overwriting one another.

Every Atom keeps its full canonical ID and 26-character email alias, but receives the shortest available prefix beginning at eight characters. For example, `atm_41kzbysa4f2ednxyqskx4a2090`, `41kzbysa`, and `41kzbysa@atoms.email` can all identify the same Atom. If a prefix collides, only the newer reference grows, so resolution remains unambiguous.

## Address proof

Sign the following UTF-8 text with the controller Ed25519 private key and send the base64url signature as `address_proof`:

    atoms-address-v1
    <ed25519 public key ID>
    <lowercase hex SHA-256 of Idempotency-Key>

The Worker verifies this proof; the private key never leaves the controller.

## Status

The API, two-way encrypted-at-rest correspondence, lifecycle controls, retention cleanup, quota enforcement, and x402 payment boundary are deployed. Creation, renewal, and reactivation each cost $0.01 in canonical USDC on Base mainnet.