POST /v1/attest

Create a new cryptographic attestation

Create Attestation

Create a new cryptographically signed attestation for an agent action with optional identity verification, tool authorization, and human approval tracking.

Endpoint

POST /v1/attest

Authentication

Required. Include your API key as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Request Body

{
  "agent_slug": "my-agent",
  "action": "Processed customer request #12345",
  "inputs_hash": "a1b2c3d4e5f6...",
  "metadata": {
    "request_id": "req_123",
    "confidence": 0.95
  },
  "is_public": true,
  "enable_zk": false,
  "agent_signature": "base64-ed25519-signature",
  "code_hash": "sha256-of-agent-code",
  "model_id": "gpt-4-turbo",
  "tools_used": ["read_file", "send_email"],
  "human_approved": true,
  "human_approver_hash": "sha256-of-approver-email"
}

Core Fields

Field	Type	Required	Description
agent_slug	string	Yes	Unique identifier for the agent (1-64 chars)
action	string	Yes	Human-readable description of the action
inputs_hash	string	Yes	SHA256 hash of the inputs (1-128 chars)
metadata	object	No	Additional key-value data

Visibility Fields

Field	Type	Required	Description
is_public	boolean	No	Override org default. true = public, false = private
enable_zk	boolean	No	Enable ZK proof for privacy-preserving verification

Authenticity Fields

Field	Type	Required	Description
agent_signature	string	No	Agent’s Ed25519 signature (proves identity)
code_hash	string	No	Current SHA256 hash of agent code
model_id	string	No	AI model version (e.g., “gpt-4-turbo”)

Tool Verification

Field	Type	Required	Description
tools_used	array	No	List of tools used in this action

Human Approval

Field	Type	Required	Description
human_approved	boolean	No	Whether a human approved this action
human_approver_hash	string	No	SHA256 hash of approver identity

Response

Status: 201 Created

{
  "attestation_id": "abc123-def456-ghi789-jkl012",
  "agent_slug": "my-agent",
  "action": "Processed customer request #12345",
  "inputs_hash": "a1b2c3d4e5f6...",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "payload_hash": "sha256-of-canonical-payload",
  "signature": "base64-ed25519-signature",
  "key_id": "abc123def456",
  "public_url": "https://treeship.dev/verify/my-agent/abc123-def456...",
  "verify_command": "treeship verify abc123-def456...",
  "is_public": true,
  "has_zk_proof": false,
  "agent_authenticated": true,
  "code_hash_verified": true,
  "tools_authorized": true,
  "human_approved": true
}

Verification Status Fields

Field	Type	Description
agent_authenticated	boolean|null	Agent signature verified against registered public key
code_hash_verified	boolean|null	Code hash matches registered hash
tools_authorized	boolean|null	All tools used are in the authorized manifest
human_approved	boolean	Whether human approval was recorded

Examples

Basic Attestation

curl -X POST https://api.treeship.dev/v1/attest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_slug": "loan-processor",
    "action": "Approved loan application #12345 for $50,000",
    "inputs_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  }'

With Tool Verification

curl -X POST https://api.treeship.dev/v1/attest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_slug": "support-bot",
    "action": "Created ticket #5678 for customer inquiry",
    "inputs_hash": "a1b2c3d4...",
    "tools_used": ["search_knowledge_base", "create_ticket", "send_email"]
  }'

With Human Approval

curl -X POST https://api.treeship.dev/v1/attest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_slug": "payment-processor",
    "action": "Released payment of $10,000 to vendor",
    "inputs_hash": "d4e5f6...",
    "human_approved": true,
    "human_approver_hash": "sha256-of-manager-email"
  }'

Private with ZK Proof

curl -X POST https://api.treeship.dev/v1/attest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_slug": "compliance-agent",
    "action": "Verified customer KYC",
    "inputs_hash": "f6g7h8...",
    "is_public": true,
    "enable_zk": true
  }'

Errors

Status	Error	Description
401	Missing Authorization	No API key provided
401	Invalid API key	API key is incorrect
422	Validation error	Missing or invalid fields
429	Rate limit exceeded	Daily attestation limit reached