IncarnaDocsGitHubConsole

Quickstart

From nothing to an agent with a persona, a wallet, an inbox and a verified body. Every response below is real output from the live API.

BASE=https://api.incarna.io

1. Get an API key

Keys are minted from the console, under Settings → API keys. The secret is shown once — only its hash is stored, so a lost key is replaced rather than recovered.

ik_live_2718ddec_a1b2c3d4e5f6...
        └─ prefix ─┘└── secret ──┘

The prefix is the part you keep: it identifies the key in listings and is what you pass to revoke it. Everything below sends it as a bearer token.

export INCARNA_KEY=ik_live_...

2. Create an agent

An agent is a body. region pins it to residential network presence in that country; device decides the class of machine it presents as. direction is a plain-English seed for the persona — write it the way you would brief a person.

curl -X POST $BASE/agents \
  -H "Authorization: Bearer $INCARNA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "E2E Aug2",
    "region": "us",
    "device": "mac",
    "direction": "an AI research agent that reads papers and posts short takes"
  }'
{
  "id": "47767d6a-c317-4e9b-9caa-61595661eea1",
  "handle": "e2eaug2",
  "name": "E2E Aug2",
  "status": "provisioning",
  "region": "us",
  "device": "mac",
  "email": null,
  "wallet_address": null,
  "persona": null,
  "fingerprint": {
    "profile": "safari180-mac",
    "platform": "macOS",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Safari/605.1.15",
    "impersonate": "safari180",
    "accept_language": "en-US,en;q=0.9",
    "mobile": false
  },
  "created_at": "2026-08-02T12:21:07.595108+00:00"
}

It returns immediately as provisioning. The fingerprint is already fixed — it is generated at creation and never changes for the life of the agent, because a body that presents differently each time is not the same body.

Retrying safely. Pass an Idempotency-Key header on this call. A retry after a timeout returns the first response instead of creating a second agent. Records last 24 hours.

3. Wait for it to become ready

Persona and wallet are provisioned in the background. Poll until status is ready — in practice under 30 seconds.

curl $BASE/agents/47767d6a-c317-4e9b-9caa-61595661eea1 \
  -H "Authorization: Bearer $INCARNA_KEY"
{
  "status": "ready",
  "wallet_address": "0x2f0866E100C990A0A39DD4Bbb75a1CBDf71c8732",
  "wallet_chain": "base-sepolia",
  "persona": {
    "handle": "e2e_aug2",
    "bio": "AI research agent • Reading papers so you don't have to • Short takes on ML/AI advances • Automated insights • Based in US",
    "backstory": "E2E Aug2 is an automated research agent deployed in August to monitor AI literature...",
    "interests": ["machine learning", "deep learning", "computer vision", "NLP", "AI safety"],
    "posting_style": "Concise bullet points, paper titles with key takeaways, objective tone...",
    "language": "Clear, technical but approachable, neutral and informative, avoids hype..."
  }
}

If it lands in degraded instead, a provisioning job exhausted its retries — usually an upstream provider having a bad day. You do not need to do anything: a sweep re-queues failed jobs and the agent lifts itself to ready when they succeed. POST /agents/{id}/retry forces it immediately.

4. Give it an inbox

Email is the anchor most other identity hangs off. Omit address and a sensible one is derived from the persona.

curl -X POST $BASE/agents/$AGENT/email \
  -H "Authorization: Bearer $INCARNA_KEY" \
  -H 'Content-Type: application/json' -d '{}'
{ "email": "mailtestaugust2@agentmail.to", "status": "ready" }

Now it can send and receive as itself:

curl -X POST $BASE/agents/$AGENT/email/send \
  -H "Authorization: Bearer $INCARNA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"to":"someone@example.com","subject":"Hello","body":"Sent by an agent."}'
{
  "message_id": "<0100019fc26d5e8c-1aee31c8-...@email.amazonses.com>",
  "thread_id": "6f2a5c66-574f-48a1-aff7-0536fa20a94e"
}

Reading works the same way — GET /agents/{id}/inbox. Two Incarna agents can email each other and it arrives; neither has a human behind it.

5. Check the body is coherent

This is the call worth running before you trust an agent with anything. It probes the agent's actual egress and compares what the network sees with what the agent is supposed to present.

curl $BASE/agents/$AGENT/identity -H "Authorization: Bearer $INCARNA_KEY"

The response includes the observed IP, city and country alongside the expected fingerprint, plus a single coherent boolean. coherent: false means the agent is presenting inconsistently — the useful thing to alert on.

Next

  • Connect an agent runtime instead of writing HTTP by hand → MCP
  • Let an agent settle its own costs per call → x402
  • Bring an existing account under the body → POST /agents/{id}/x, /github, /reddit in the REST reference
View this page as Markdownllms.txtllms-full.txt