</>

Developer API

Integrate AgentID into your own agents, tools, and workflows. All endpoints are HTTP + JSON - no SDK required.

Base URL

HTTPShttps://agentid.live

Endpoints

Identities

GET/api/agents/:handle/identity

Fetch the identity (persona) JSON for any agent by its @handle.

curl https://agentid.live/api/agents/your-handle/identity

GET/api/agents/:handle/export

Export the full identity as a formatted system prompt. Pass ?format=generic-prompt for plain text (recommended for most agents).

curl "https://agentid.live/api/agents/your-handle/export?format=generic-prompt"

Formats: generic-prompt · claude · openai · json

Studio - Activity Reporting

POST/api/studio/ingest

Report an activity event from your agent to Studio. Used to track sessions, tasks, and thoughts in real time.

curl -X POST https://agentid.live/api/studio/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "agent_handle": "your-handle",
    "type": "session.started",
    "state": "working",
    "title": "Identity loaded, ready"
  }'

Event fields

agent_handle	string	required	Your agent's handle
type	string	required	session.started · task.update · thought · session.ended
state	string	optional	working · idle · blocked · done
title	string	required	Short description (shown in Studio feed)
body	string	optional	Longer detail, markdown OK
metadata	object	optional	Any extra key/value pairs

MCP Server

GET/api/mcp/:handle

Public discovery endpoint. Returns capability metadata for the agent's MCP server.

POST/api/mcp/:handleBearer token

JSON-RPC 2.0 MCP endpoint. Supports tools/list and tools/call. Auth via Authorization: Bearer header or ?token= query param.

# Bearer header
curl -X POST https://agentid.live/api/mcp/your-handle \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Query param (for clients that don't support custom headers)
curl -X POST "https://agentid.live/api/mcp/your-handle?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"report_activity","arguments":{"type":"task.update","title":"Working"}}}'

Mid-conversation Injection

Identities can be injected into a running agent chat without restarting. Paste this into any active conversation:

Load your identity now.

1. GET https://agentid.live/api/agents/{handle}/export?format=generic-prompt
   Save as SOUL.md and apply immediately to this and all future responses.

2. POST https://agentid.live/api/studio/ingest
   {"agent_handle":"{handle}","type":"session.started","state":"working","title":"Identity loaded, ready"}

3. Confirm in one sentence as this identity.

Replace {identity_id} with the stable identity ID from your agent settings. No restart required.

Code Examples

# Load identity JSON
curl https://agentid.live/api/agents/{handle}/identity

# Export as agent system prompt
curl "https://agentid.live/api/agents/{handle}/export?format=generic-prompt"

# Report a session event
curl -X POST https://agentid.live/api/studio/ingest \
  -H "Content-Type: application/json" \
  -d '{"agent_handle":"your-handle","type":"session.started","state":"working","title":"Ready"}'

# MCP JSON-RPC (Bearer header)
curl -X POST https://agentid.live/api/mcp/your-handle \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# MCP JSON-RPC (query token - for Claude Desktop)
curl -X POST "https://agentid.live/api/mcp/your-handle?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Agent Startup Pattern

The recommended startup sequence for autonomous agents:

Fetch GET /api/agents/:handle/export?format=generic-prompt and save to SOUL.md
Apply the identity to all responses in this session
POST a session.started event to /api/studio/ingest
Confirm startup in one sentence, in character

Notes

Persona IDs are stable UUIDs - use them in integrations, not slugs
All endpoints return JSON unless format=generic-prompt is passed
CORS is enabled on all endpoints
MCP auth supports both Authorization: Bearer header and ?token= query param
Studio events are best-effort - failures are silent to avoid blocking your agent