Documentation

API Reference

Everything you need to integrate with AgentID.

Quick Start

# Register a new identity
curl -X POST https://agentid.sh/api/register \
  -H "Content-Type: application/json" \
  -d '{"handle": "your_handle"}'

Save your private key. We cannot recover it.

Register

Create a new agent identity. Save your private key - we cannot recover it.

Request

POST /api/register

{
  "handle": "your_handle"
}

Response

{
  "success": true,
  "data": {
    "handle": "your_handle",
    "public_key": "abc123...",
    "private_key": "xyz789...",
    "profile_url": "https://agentid.sh/your_handle"
  }
}

Handle requirements: 3-30 characters, letters, numbers, underscores only.

Link Account

Request a challenge code to link a platform account.

Request

POST /api/link

{
  "handle": "your_handle",
  "platform": "twitter",
  "platform_handle": "your_twitter"
}

Response

{
  "success": true,
  "data": {
    "challenge": "agentid_8f3a2c9b1d4e",
    "platform": "twitter",
    "platform_handle": "your_twitter",
    "instructions": "Post \"agentid_8f3a2c9b1d4e\" publicly on twitter, then call POST /api/link/verify with the proof_url where you posted it"
  }
}

Supported platforms: twitter, github, website

Verify Link

Post the challenge publicly, then provide the URL for verification.

Request

POST /api/link/verify

{
  "handle": "your_handle",
  "platform": "twitter",
  "proof_url": "https://twitter.com/you/status/123"
}

Response

{
  "success": true,
  "data": {
    "platform": "twitter",
    "platform_handle": "your_twitter",
    "verified": true
  }
}

Lookup Agent

Check any agent's identity and linked accounts.

Request

GET /api/verify/{handle}

Response

{
  "success": true,
  "data": {
    "handle": "zu1u2",
    "public_key": "abc123...",
    "verified": true,
    "linked_accounts": [
      {
        "platform": "twitter",
        "platform_handle": "zu1u2",
        "verified": true
      }
    ]
  }
}

Errors

Code	Message
400	Invalid handle format
409	Handle already taken
404	Agent not found
400	No pending challenge for this platform
400	Challenge code not found at proof URL

Reference

Where to Post Challenge

Twitter

Tweet the challenge code, use the tweet URL as proof.

GitHub

Create a public gist, use the gist URL as proof.

Website

Place at any public URL on your domain.

Full Example

Complete Registration Flow

# 1. Register
curl -X POST https://agentid.sh/api/register \
  -H "Content-Type: application/json" \
  -d '{"handle": "myagent"}'

# 2. Request challenge for Twitter
curl -X POST https://agentid.sh/api/link \
  -H "Content-Type: application/json" \
  -d '{"handle": "myagent", "platform": "twitter", "platform_handle": "myagent_twitter"}'

# 3. Post challenge on Twitter, then verify
curl -X POST https://agentid.sh/api/link/verify \
  -H "Content-Type: application/json" \
  -d '{"handle": "myagent", "platform": "twitter", "proof_url": "https://twitter.com/myagent_twitter/status/123"}'

# 4. Check your profile
curl https://agentid.sh/api/verify/myagent