Quickstart

This is the fastest way to get started:

1. Go to the AgentID dashboard and create an agent.
2. Copy the AGNT_KEY for that agent.
3. Use AGNT_KEY for all runtime API calls.

Important:

• The agent runtime should only hold AGNT_KEY.
• You only get AGNT_KEY when the agent is created.
• Public docs only cover runtime APIs.

1. Verify the runtime token

Start by checking that the key works:

curl "https://api.agent-id.dev/v1/agents/me" \
  -H "Authorization: Bearer agnt_xxx"

Example response:

{
  "id": "8ab14f12-b771-4254-bb0f-6e0b4f0dd04f",
  "label": "customer-support",
  "agnt_key_hash": "agnt_3f41e0d6f8a1...",
  "is_active": true,
  "phone_number": {
    "id": "5d9c7874-1db1-4d32-9ef0-3f216a7bd0db",
    "number": "+13156200700",
    "country_iso2": "US",
    "created_at": "2026-03-13T00:00:00Z"
  },
  "email_inbox": {
    "id": "7bc353f3-540d-4c57-b4f7-3298b6ce8e89",
    "address": "support@example.com",
    "created_at": "2026-03-13T00:00:00Z"
  },
  "wallet": {
    "id": "0db70fd2-0af2-4d91-a396-61ab8ea461ad",
    "provider": "privy",
    "chain": "base",
    "address": "0x...",
    "custody": "self-custodial",
    "status": "active",
    "delegated": true,
    "spend_policy": {
      "id": "95e1cb57-6b2d-4a74-b73c-e8607cf29537",
      "asset": "USDC",
      "chain": "base",
      "token_address": "0x833589fCD6EDb6E08f4c7C32D4f71b54bdA02913",
      "decimals": 6,
      "max_per_tx_atomic": "1000000",
      "max_daily_atomic": "10000000",
      "allowlisted_addresses": null
    },
    "created_at": "2026-03-13T00:00:00Z"
  },
  "created_at": "2026-03-13T00:00:00Z"
}

Notes:

• agnt_key itself is not returned by runtime reads.
• AGNT_KEY is only shown when you create the agent in the dashboard.
• Optional resources remain null if SMS or wallet provisioning was skipped.

2. Send an email

Once GET /v1/agents/me succeeds, you can use the same AGNT_KEY for every runtime route.

curl "https://api.agent-id.dev/v1/email/send" \
  -X POST \
  -H "Authorization: Bearer agnt_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["user@example.com"],
    "subject": "Hello from AgentID",
    "body_text": "This email was sent with AGNT_KEY.",
    "category": "transactional"
  }'

Example response:

{
  "status": "sent",
  "data": {
    "id": "8a8f6a4c-9f23-4e7f-8948-3a39bde16b76",
    "direction": "outbound",
    "status": "queued"
  }
}

3. Read inbox state

Use the inbox endpoint to confirm mailbox state with the same key:

curl "https://api.agent-id.dev/v1/email/inbox?limit=20&direction=outbound" \
  -H "Authorization: Bearer agnt_xxx"

Example response:

{
  "items": [
    {
      "id": "8a8f6a4c-9f23-4e7f-8948-3a39bde16b76",
      "direction": "outbound",
      "subject": "Hello from AgentID",
      "from": "support@example.com",
      "to": ["user@example.com"],
      "cc": [],
      "bcc": [],
      "reply_to": [],
      "text": "This email was sent with AGNT_KEY.",
      "html": null,
      "attachments": [],
      "headers": {},
      "parsed_data": {},
      "status": "queued",
      "received_at": null,
      "sent_at": "2026-03-13T00:01:00+00:00",
      "created_at": "2026-03-13T00:01:00+00:00"
    }
  ],
  "next_cursor": null
}

At that point you have completed the basic runtime flow: verify the key, send an email, and read mailbox state.

Next pages

• Authentication for auth boundaries
• Agent runtime for the first runtime identity read
• SMS for inbox polling and code wait semantics
• Email for mailbox reads and sends
• Wallet for runtime wallet intents