Skip to main content

​
Identity API

The Identity API allows you to register agent identities, manage tool manifests, and verify authenticity.

​
Register Agent Identity

Register an agent with cryptographic identity proofs. 
POST /v1/identity/register

​
Request

{
  "slug": "my-agent",
  "name": "My AI Agent",
  "description": "Handles customer support",
  "public_key_pem": "-----BEGIN PUBLIC KEY-----\n...",
  "code_hash": "sha256-of-agent-code",
  "model_id": "gpt-4-turbo",
  "domain": "agent.example.com"
}
FieldTypeRequiredDescription
slugstringYesUnique agent identifier
namestringNoHuman-readable name
descriptionstringNoAgent description
public_key_pemstringNoEd25519 public key in PEM format
code_hashstringNoSHA256 hash of agent code
model_idstringNoAI model identifier
domainstringNoDomain to verify ownership

​
Response

{
  "slug": "my-agent",
  "registered": true,
  "identity_score": 45,
  "verification_challenges": {
    "domain": "Add TXT record: _treeship-verify.agent.example.com = abc123..."
  },
  "public_url": "https://treeship.dev/verify/my-agent"
}

​
Get Agent Identity

Retrieve identity information and verification status. 
GET /v1/identity/{slug}

​
Response

{
  "slug": "my-agent",
  "name": "My AI Agent",
  "identity_score": 75,
  "verified_proofs": [
    {"type": "domain", "value": "agent.example.com", "verified_at": "2024-01-15T10:30:00Z"}
  ],
  "code_hash": "e3b0c442...",
  "model_id": "gpt-4-turbo",
  "verified_domain": "agent.example.com",
  "tool_manifest_hash": "a1b2c3d4...",
  "tools": ["read_file", "send_email", "search_web"],
  "created_at": "2024-01-10T08:00:00Z"
}

​
Set Tool Manifest

Register authorized tools for an agent. 
POST /v1/identity/{slug}/tools

​
Request

{
  "tools": ["read_file", "write_file", "send_email", "search_web"],
  "tool_descriptions": {
    "send_email": "Send email to approved domains only",
    "search_web": "Search public web only"
  }
}

​
Response

{
  "agent_slug": "my-agent",
  "tool_manifest_hash": "e3b0c442...",
  "tools": ["read_file", "search_web", "send_email", "write_file"],
  "signature": "base64-signature...",
  "updated_at": "2024-01-15T10:30:00Z"
}

​
Get Tool Manifest

Retrieve the current tool manifest. 
GET /v1/identity/{slug}/tools

​
Response

Same as Set Tool Manifest response.

​
Verify Tools Used

Check if tools used are in the authorized manifest. 
POST /v1/identity/{slug}/verify-tools?tools_used=read_file&tools_used=send_email

​
Response

{
  "verified": true,
  "authorized_tools": ["read_file", "send_email"],
  "unauthorized_tools": [],
  "manifest_hash": "e3b0c442..."
}
Or if unauthorized tools were used: 
{
  "verified": false,
  "authorized_tools": ["read_file"],
  "unauthorized_tools": ["delete_database"],
  "manifest_hash": "e3b0c442..."
}

​
Domain Verification

​
Get Domain Challenge

GET /v1/identity/{slug}/domain-challenge?domain=agent.example.com

​
Response

{
  "agent_slug": "my-agent",
  "domain": "agent.example.com",
  "challenge_token": "abc123def456...",
  "verification_methods": [
    {"method": "dns_txt", "instruction": "Add TXT record: _treeship-verify.agent.example.com = abc123..."},
    {"method": "meta_tag", "instruction": "Add to <head>: <meta name=\"treeship-verify\" content=\"abc123...\">"},
    {"method": "file", "instruction": "Create file: https://agent.example.com/.well-known/treeship-verify.txt containing: abc123..."}
  ],
  "expires_at": "2024-01-16T10:30:00Z"
}

​
Verify Domain

POST /v1/identity/{slug}/verify-domain

{
  "agent_slug": "my-agent",
  "domain": "agent.example.com"
}

​
Response

{
  "verified": true,
  "domain": "agent.example.com",
  "verified_at": "2024-01-15T10:35:00Z"
}

​
Voice Fingerprint

​
Register Voice Fingerprint

POST /v1/identity/{slug}/voice-fingerprint

{
  "fingerprint_hash": "sha256-of-voice-embedding",
  "provider": "elevenlabs",
  "sample_count": 3
}

​
Response

{
  "registered": true,
  "agent_slug": "my-agent",
  "fingerprint_hash": "e3b0c442...",
  "provider": "elevenlabs"
}

​
Verify Voice

POST /v1/identity/{slug}/verify-voice?fingerprint_hash=sha256-of-incoming-voice

​
Response

{
  "verified": true,
  "agent_slug": "my-agent",
  "confidence": 1.0,
  "safe_for_payment": true
}

​
Identity Score

The identity score (0-100) is calculated based on verified proofs:
ProofPoints
Basic registration10
Public key registered20
Code hash registered15
Model ID specified5
Domain verified25
Tool manifest registered15
Additional verified proofsup to 10
Higher scores indicate stronger identity verification.