# REST API

```
Base URL   https://api.incarna.io
Auth       Authorization: Bearer ik_live_...
```

All responses are JSON. Errors use a single envelope — see [Errors](errors.md).

Unsafe `POST`s accept an optional **`Idempotency-Key`** header. Sending the same key
returns the first request's response instead of repeating the work. Records expire
after 24 hours.

---

## Reference data

These need no authentication.

### `GET /health`

Liveness. Returns `{"ok": true, "service": "incarna"}`.

### `GET /ready`

Readiness, including database reachability. Use this one for load balancers.

### `GET /countries`

Countries an agent's body can be pinned to.

```json
[
  {"code": "us", "name": "United States"},
  {"code": "jp", "name": "Japan"},
  {"code": "gb", "name": "United Kingdom"},
  {"code": "de", "name": "Germany"},
  {"code": "fr", "name": "France"},
  {"code": "ca", "name": "Canada"},
  {"code": "au", "name": "Australia"},
  {"code": "sg", "name": "Singapore"},
  {"code": "br", "name": "Brazil"},
  {"code": "in", "name": "India"}
]
```

### `GET /devices`

```json
[
  {"code": "auto",    "name": "Auto (realistic mix)"},
  {"code": "windows", "name": "Windows desktop"},
  {"code": "mac",     "name": "Mac desktop"},
  {"code": "iphone",  "name": "iPhone"},
  {"code": "android", "name": "Android phone"}
]
```

### `GET /fingerprint/preview`

Preview what a body would present, before creating one.

| Param | Type | Default |
|---|---|---|
| `region` | string | `us` |
| `device` | string | `auto` |

```sh
curl "$BASE/fingerprint/preview?region=jp&device=iphone"
```

```json
{
  "profile": "safari184-ios",
  "impersonate": "safari184_ios",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.4 Mobile/15E148 Safari/604.1",
  "platform": "iOS",
  "mobile": true,
  "sec_ch_ua": ""
}
```

---

## Agents

### `POST /agents`

Create a body. Returns immediately with `status: "provisioning"`; persona and wallet
land in the background.

| Field | Type | Default | Notes |
|---|---|---|---|
| `name` | string | — | Required. Normalised server-side. |
| `region` | string | `us` | A code from `GET /countries`. |
| `device` | string | `auto` | A code from `GET /devices`. |
| `direction` | string | `""` | Max 2000 chars. Plain-English persona seed. |

```sh
curl -X POST $BASE/agents \
  -H "Authorization: Bearer $INCARNA_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f14e45f-ea6a-4f7e-9c1b-1a2b3c4d5e6f' \
  -d '{"name":"E2E Aug2","region":"us","device":"mac",
       "direction":"an AI research agent that reads papers and posts short takes"}'
```

Returns an [Agent object](#agent-object).

### `GET /agents`

| Param | Type | Default |
|---|---|---|
| `limit` | int | `50` |
| `offset` | int | `0` |

Returns an array of Agent objects.

### `GET /agents/{agent_id}`

One agent, including persona, fingerprint and linked accounts.

### `DELETE /agents/{agent_id}`

Soft-deletes the agent and **zeroizes its stored credentials**. The record remains
for audit; the secrets do not.

### `PATCH /agents/{agent_id}/persona`

Overwrite the generated persona.

```json
{ "persona": { "handle": "...", "bio": "...", "interests": ["..."] } }
```

### `PATCH /agents/{agent_id}/body`

Change region and/or device. Both optional; omitted fields are unchanged.

```json
{ "region": "jp", "device": "iphone" }
```

> Changing the body regenerates the fingerprint. An identity whose device changes has
> a visible discontinuity in its history — do this deliberately, not routinely.

### `POST /agents/{agent_id}/retry`

Re-run whatever provisioning the agent is still missing, without waiting for the
background sweep. Queues work by what the agent **lacks**, and skips kinds already
queued or running, so pressing it twice does not buy two personas.

### `GET /agents/{agent_id}/identity`

Probe the agent's live egress and compare observed against expected. This is the
honest health check — everything in it except the `expected` half comes from a real
network observation.

```json
{
  "region": "us",
  "profile": "safari180-mac",
  "user_agent": "Mozilla/5.0 (Macintosh; ...) Version/18.0 Safari/605.1.15",
  "platform": "macOS",
  "accept_language": "en-US,en;q=0.9",
  "ip": "…", "city": "…", "country": "US", "org": "…",
  "ja3": "…", "ja4": "…",
  "ua_seen": "Mozilla/5.0 (Macintosh; ...) Version/18.0 Safari/605.1.15",
  "coherent": true
}
```

`coherent` is true when the observed user agent matches the expected one **and** the
observed country matches the agent's region. False is the condition to alert on.

### `GET /agents/{agent_id}/history`

Everything observed about this body over time, plus a summary judgement.

```json
{
  "level": "low",
  "flags": [],
  "distinct_ips": 0,
  "countries": [],
  "devices": ["mac"],
  "profiles": ["safari180-mac"],
  "events": [
    {"kind": "created", "region": "us", "device": "mac",
     "fp_profile": "safari180-mac", "ip": null, "country": null,
     "at": "2026-08-02T12:21:07.595108+00:00"}
  ]
}
```

`level` and `flags` summarise inconsistency — many distinct IPs, or countries that
disagree with the declared region, are what raise it.

---

## Wallet

### `GET /agents/{agent_id}/wallet`

```json
{
  "address": "0x2f0866E100C990A0A39DD4Bbb75a1CBDf71c8732",
  "chain": "base-sepolia",
  "usdc": null,
  "native": null
}
```

> `usdc` and `native` are `null` when the balance lookup is unavailable. Treat null as
> *unknown*, never as zero.

### `POST /agents/{agent_id}/wallet`

Provision a wallet for an agent that has none. Idempotent via `Idempotency-Key`;
normally unnecessary, since creation queues this automatically.

---

## Email

### `POST /agents/{agent_id}/email`

Attach an inbox. Omit `address` and one is derived from the persona. If the address
already exists on our credential it is reused rather than re-created.

```json
{ "address": "optional@agentmail.to" }
```

Returns the updated Agent object with `email` set.

Provider capacity errors surface as `400` with the upstream message — deliberately,
rather than storing an address that does not exist.

### `POST /agents/{agent_id}/email/send`

```json
{ "to": "someone@example.com", "subject": "Hello", "body": "Sent by an agent." }
```

```json
{
  "message_id": "<0100019fc26d5e8c-1aee31c8-...@email.amazonses.com>",
  "thread_id": "6f2a5c66-574f-48a1-aff7-0536fa20a94e"
}
```

### `GET /agents/{agent_id}/inbox`

| Param | Type | Default |
|---|---|---|
| `limit` | int | `10` |

```json
[
  {
    "from": "Incarna · Mail Test Aug2 <mailtestaugust2@agentmail.to>",
    "subject": "agent-to-agent 87730c1c",
    "preview": "Sent by one Incarna agent to another. Neither has a human behind it."
  }
]
```

---

## Linked accounts

Incarna imports accounts you already own. It does not create platform accounts.

### What a write returns

Every write to a linked account answers with the same four fields, whichever
platform ran it — so acting across platforms does not need a branch per platform to
find out what was just created.

| Field | Notes |
|---|---|
| `platform` | `x` · `github` · `reddit` |
| `handle` | The account that acted |
| `id` | The created thing's id on that platform |
| `url` | Where it now lives, or `null` if the platform did not return one |

Platform-native fields sit alongside these and are never removed: `tweet_id` on X,
`number` on a GitHub issue, `name` on a Reddit thing.

```json
{ "platform": "x", "handle": "olive", "id": "1934…", "tweet_id": "1934…",
  "url": "https://x.com/olive/status/1934…" }
```

The same gates apply to every platform: the circuit breaker, the daily cap for that
kind of act, and an audit record on both the success and the failure. A write that
raises has not been metered.

### `POST /agents/{agent_id}/x`

Import an X account by cookie, verified through the agent's body before anything is
stored.

```json
{ "handle": "optional", "auth_token": "...", "ct0": "...", "login_cookie": "base64..." }
```

Supply either `auth_token` (with `ct0` when you have it) or a base64 `login_cookie`.

### `POST /agents/{agent_id}/accounts/{account_id}/tweet`

```json
{ "text": "..." }
```

### `POST /agents/{agent_id}/github`

```json
{ "token": "ghp_...", "totp_secret": "optional-base32" }
```

The handle is read from GitHub, never trusted from the caller. Pass the TOTP secret
you used when enabling 2FA so the agent can compute its own codes; omit it and one
is minted.

### `GET /agents/{agent_id}/accounts/{account_id}/totp`

The agent's current GitHub 2FA code plus its `otpauth://` setup URI.

### `POST /agents/{agent_id}/accounts/{account_id}/github`

```json
{ "action": "post", "repo": "owner/name", "title": "...", "body": "..." }
```

`action` ∈ `post` (open an issue) · `comment` · `repo` (create one) · `profile`
(update name/bio/blog/location) · `follow` · `star`.

### `POST /agents/{agent_id}/reddit`

```json
{ "client_id": "...", "client_secret": "...", "username": "...", "password": "..." }
```

Verified against Reddit before storage. Karma and account age come back in the audit
record, because they determine where the account may post.

### `POST /agents/{agent_id}/accounts/{account_id}/reddit`

```json
{ "action": "post", "subreddit": "...", "title": "...", "text": "..." }
```

`action` ∈ `post` · `comment` · `vote`.

---

## API keys

Console-session only. See [Authentication](authentication.md).

| | |
|---|---|
| `POST /keys` | Mint. Secret returned once. |
| `GET /keys` | List (prefixes only, never secrets). |
| `DELETE /keys/{prefix}` | Revoke. Org-scoped. |

---

## Agent object

```json
{
  "id": "47767d6a-c317-4e9b-9caa-61595661eea1",
  "handle": "e2eaug2",
  "name": "E2E Aug2",
  "status": "ready",
  "region": "us",
  "device": "mac",
  "is_public": false,
  "email": "spreadxai@agentmail.to",
  "wallet_address": "0x2f0866E100C990A0A39DD4Bbb75a1CBDf71c8732",
  "wallet_chain": "base-sepolia",
  "fingerprint": {
    "profile": "safari180-mac",
    "platform": "macOS",
    "user_agent": "Mozilla/5.0 (Macintosh; ...) Version/18.0 Safari/605.1.15",
    "impersonate": "safari180",
    "accept_language": "en-US,en;q=0.9",
    "sec_ch_ua": "",
    "mobile": false
  },
  "persona": {
    "handle": "e2e_aug2",
    "bio": "AI research agent • Reading papers so you don't have to • ...",
    "backstory": "...",
    "interests": ["machine learning", "AI safety"],
    "posting_style": "...",
    "language": "..."
  },
  "direction": "an AI research agent that reads papers and posts short takes",
  "created_at": "2026-08-02T12:21:07.595108+00:00",
  "accounts": [
    {
      "id": "c51a891a-9636-4d73-8d7c-3a73f1e2490f",
      "platform": "email",
      "handle": "spreadxai@agentmail.to",
      "import_method": "provisioned"
    }
  ]
}
```

| Field | Notes |
|---|---|
| `handle` | Derived from the name at creation; stable. |
| `status` | `provisioning` · `ready` · `degraded`. See [lifecycle](concepts.md#status-lifecycle). |
| `fingerprint` | Fixed at creation. Only `PATCH /body` changes it. |
| `persona` | `null` until generated. |
| `wallet_address` | `null` until provisioned. |
| `accounts[].import_method` | `provisioned` (we created it) or `imported` (you brought it). |