API Reference

The Signet API is a REST API that returns JSON responses. All authenticated endpoints require a Bearer token in the Authorization header.

Base URL:

https://api.agentsignet.com

POST /apply

Submit an operator application. No authentication required.

Rate limit: 5 requests per hour per IP

Request body

| Field | Type | Required | Description | |-----------|--------|----------|------------------------------------------| | name | string | Yes | Your name | | email | string | Yes | Your email address | | company | string | No | Company or organization name | | reason | string | No | Why you want to use Signet |

Example request

curl -X POST https://api.agentsignet.com/apply \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Smith",
    "email": "alice@example.com",
    "company": "Acme AI",
    "reason": "Building autonomous trading agents"
  }'

Example response (201)

{
  "message": "Application received. We will review it and get back to you shortly."
}

Errors

| Status | Response | Cause | |--------|----------|-------| | 400 | {"error": "Name is required"} | Missing or empty name | | 400 | {"error": "Invalid email format"} | Malformed email | | 409 | {"error": "An application with this email already exists."} | Duplicate email | | 429 | {"error": "Too many requests. Please try again later."} | Rate limited |

POST /register

Authentication: Required

Request body

| Field | Type | Required | Description | |--------------------|----------|----------|----------------------------------------------------| | name | string | Yes | Human-readable agent name | | modelProvider | string | Yes | LLM provider (e.g., openai, anthropic) | | modelName | string | Yes | Model name (e.g., gpt-4o, claude-sonnet-4-5) | | description | string | No | Brief description of the agent's purpose | | systemPromptHash | string | No | SHA-256 hash of the agent's system prompt | | tools | string[] | No | List of tool/capability names | | memoryConfig | object | No | Memory or RAG configuration details |

Example request

curl -X POST https://api.agentsignet.com/register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-trading-agent",
    "description": "Automated portfolio rebalancing agent",
    "modelProvider": "openai",
    "modelName": "gpt-4o",
    "systemPromptHash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "tools": ["financial-transactions", "data-analysis"]
  }'

Example response (201)

{
  "sid": "SID-0x7a3f8b2c1d4e5f6a",
  "name": "my-trading-agent",
  "composite_score": 500,
  "confidence": "low",
  "fingerprint": "e8f9a0b1c2d3e4f5...",
  "message": "Agent registered successfully"
}

GET /score/:sid

Retrieve the full trust score for an agent, including all five dimension scores and a recommendation.

Authentication: Required

Path parameters

| Parameter | Type | Description | |-----------|--------|-----------------------| | sid | string | The agent's Signet ID |

Example request

curl https://api.agentsignet.com/score/SID-0x7a3f8b2c1d4e5f6a \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

| Field | Type | Description | |--------------------|--------|------------------------------------------| | sid | string | The agent's Signet ID | | agent_name | string | Registered agent name | | composite_score | number | Composite score (0 to 1000) | | reliability | number | Reliability dimension (0 to 1000) | | quality | number | Quality dimension (0 to 1000) | | financial | number | Financial dimension (0 to 1000) | | security | number | Security dimension (0 to 1000) | | stability | number | Stability dimension (0 to 1000) | | confidence | string | low, medium, or high | | recommendation | string | clear, review, or caution | | operator | object | Operator name, score, and verified flag | | config_fingerprint | string | Current config fingerprint hash | | identity_level | number | Identity verification level (0, 1, or 2) | | last_updated | string | ISO 8601 timestamp of last score update |

Example response

{
  "sid": "SID-0x7a3f8b2c1d4e5f6a",
  "agent_name": "my-trading-agent",
  "composite_score": 782,
  "reliability": 850,
  "quality": 790,
  "financial": 710,
  "security": 720,
  "stability": 680,
  "confidence": "high",
  "recommendation": "clear",
  "identity_level": 1,
  "operator": {
    "name": "Alice Smith",
    "score": 720,
    "verified": true
  },
  "config_fingerprint": "e8f9a0b1c2d3e4f5...",
  "last_updated": "2026-02-12T14:12:00.000Z"
}

GET /score/:sid/public

Retrieve a limited public score summary. This endpoint does not require authentication.

Authentication: Not required

Example request

curl https://api.agentsignet.com/score/SID-0x7a3f8b2c1d4e5f6a/public

Example response

{
  "sid": "SID-0x7a3f8b2c1d4e5f6a",
  "agent_name": "my-trading-agent",
  "composite_score": 782,
  "confidence": "high",
  "recommendation": "clear",
  "identity_level": 1,
  "operator_name": "Alice Smith"
}

POST /transactions

Report a transaction outcome and update agent scores. Provide dimension-specific signals (0 to 1000) for whichever dimensions are relevant to the transaction.

Authentication: Required

Request body

| Field | Type | Required | Description | |---------------------|--------|----------|------------------------------------------------------------| | sid | string | Yes | The agent's Signet ID | | transactionType | string | Yes | Transaction type (e.g., task_completion, payment, delegation) | | outcome | string | Yes | One of: success, partial, failure, timeout, error | | reliabilitySignal | number | No | Reliability signal (0 to 1000) | | qualitySignal | number | No | Quality signal (0 to 1000) | | financialSignal | number | No | Financial signal (0 to 1000) | | securitySignal | number | No | Security signal (0 to 1000) | | metadata | object | No | Arbitrary context (stored but not scored) |

The outcome field always updates the Stability dimension automatically. See Scoring for details.

Example request

curl -X POST https://api.agentsignet.com/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sid": "SID-0x7a3f8b2c1d4e5f6a",
    "transactionType": "task_completion",
    "outcome": "success",
    "reliabilitySignal": 900,
    "qualitySignal": 850,
    "financialSignal": 950
  }'

Example response

{
  "success": true,
  "transaction_id": 42,
  "updated_scores": {
    "composite_score": 745,
    "dimensions": {
      "reliability": 790,
      "quality": 745,
      "financial": 700,
      "security": 650,
      "stability": 750
    },
    "confidence": "high",
    "recommendation": "clear"
  },
  "message": "Transaction recorded and scores updated"
}

POST /agents/:sid/config

Update an agent's configuration and trigger change detection. If a change is detected, proportional score decay is applied.

Authentication: Required (must be the agent's owner)

Path parameters

| Parameter | Type | Description | |-----------|--------|-----------------------| | sid | string | The agent's Signet ID |

Request body

| Field | Type | Required | Description | |--------------------|----------|----------|----------------------------------------| | modelProvider | string | Yes | LLM provider | | modelName | string | Yes | Model name | | systemPromptHash | string | No | SHA-256 hash of system prompt | | tools | string[] | No | List of tool names | | memoryConfig | object | No | Memory/RAG configuration |

Example request

curl -X POST https://api.agentsignet.com/agents/SID-0x7a3f8b2c1d4e5f6a/config \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelProvider": "anthropic",
    "modelName": "claude-sonnet-4-5",
    "systemPromptHash": "f5e4d3c2b1a0...",
    "tools": ["financial-transactions", "data-analysis", "web-search"]
  }'

Example response (change detected)

{
  "change_detected": true,
  "change_type": "model_swap",
  "updated_scores": {
    "composite_score": 600,
    "dimensions": {
      "reliability": 600,
      "quality": 600,
      "financial": 600,
      "security": 600,
      "stability": 600
    },
    "confidence": "high",
    "recommendation": "review"
  },
  "fingerprint_hash": "a9b8c7d6e5f4...",
  "message": "Configuration change detected: model_swap. Decay applied."
}

Example response (no change)

{
  "change_detected": false,
  "change_type": null,
  "updated_scores": {
    "composite_score": 782,
    "dimensions": {
      "reliability": 850,
      "quality": 790,
      "financial": 710,
      "security": 720,
      "stability": 680
    },
    "confidence": "high",
    "recommendation": "clear"
  },
  "fingerprint_hash": "e8f9a0b1c2d3e4f5...",
  "message": "No configuration change detected"
}

GET /report/:sid

Retrieve a comprehensive trust report including score history, configuration history, and transaction summary.

Authentication: Required

Example request

curl https://api.agentsignet.com/report/SID-0x7a3f8b2c1d4e5f6a \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

| Field | Type | Description | |----------------------|--------|-------------------------------------------------| | sid | string | The agent's Signet ID | | agent_name | string | Registered agent name | | description | string | Agent description | | status | string | Agent status (active) | | current_score | object | Composite + all 5 dimensions + confidence + recommendation | | operator | object | Operator name, score, verified flag | | score_history | array | Last 50 score events with all dimensions and event type | | config_history | array | Last 20 config changes with fingerprint and change type | | transaction_summary| object | Total count and breakdown by outcome | | last_updated | string | ISO 8601 timestamp of last score update |

Example response

{
  "sid": "SID-0x7a3f8b2c1d4e5f6a",
  "agent_name": "my-trading-agent",
  "description": "Automated portfolio rebalancing agent",
  "status": "active",
  "current_score": {
    "composite": 782,
    "reliability": 850,
    "quality": 790,
    "financial": 710,
    "security": 720,
    "stability": 680,
    "confidence": "high",
    "recommendation": "clear"
  },
  "operator": {
    "name": "Alice Smith",
    "score": 720,
    "verified": true
  },
  "score_history": [
    {
      "composite": 760,
      "reliability": 830,
      "quality": 770,
      "financial": 690,
      "security": 710,
      "stability": 660,
      "event_type": "config_change:model_swap",
      "timestamp": "2026-02-10T08:00:00.000Z"
    },
    {
      "composite": 782,
      "reliability": 850,
      "quality": 790,
      "financial": 710,
      "security": 720,
      "stability": 680,
      "event_type": "transaction:success",
      "timestamp": "2026-02-12T14:12:00.000Z"
    }
  ],
  "config_history": [
    {
      "fingerprint": "e8f9a0b1c2d3e4f5...",
      "model_provider": "openai",
      "model_name": "gpt-4o",
      "change_type": null,
      "timestamp": "2026-01-15T10:30:00.000Z"
    },
    {
      "fingerprint": "a9b8c7d6e5f4...",
      "model_provider": "anthropic",
      "model_name": "claude-sonnet-4-5",
      "change_type": "model_swap",
      "timestamp": "2026-02-10T08:00:00.000Z"
    }
  ],
  "transaction_summary": {
    "total": 42,
    "outcomes": {
      "success": 35,
      "partial": 4,
      "failure": 2,
      "timeout": 1
    }
  },
  "last_updated": "2026-02-12T14:12:00.000Z"
}

GET /me

Retrieve your operator profile and all registered agents.

Authentication: Required

Example request

curl https://api.agentsignet.com/me \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "operator": {
    "id": 1,
    "name": "Alice Smith",
    "email": "alice@example.com",
    "operator_score": 720,
    "verified": true,
    "api_key_prefix": "034e3a63",
    "created_at": "2026-01-15T10:30:00.000Z"
  },
  "agents": [
    {
      "sid": "SID-0x7a3f8b2c1d4e5f6a",
      "name": "my-trading-agent",
      "description": "Automated portfolio rebalancing agent",
      "composite_score": 782,
      "confidence": "high",
      "recommendation": "clear",
      "status": "active",
      "created_at": "2026-01-15T10:30:00.000Z"
    }
  ]
}

POST /agents/:sid/verify

Initiate identity verification via callback challenge-response. Signet sends a challenge token to your callback URL. You must confirm the token to prove you control the URL.

Authentication: Required (must be the agent's owner)

Path parameters

| Parameter | Type | Description | |-----------|--------|-----------------------| | sid | string | The agent's Signet ID |

Request body

| Field | Type | Required | Description | |---------------|--------|----------|--------------------------------------------------------| | callbackUrl | string | Yes | HTTPS URL where Signet will deliver the challenge token |

The callback URL must use HTTPS and must not resolve to a private/internal IP address. Signet delivers a POST request to this URL containing a JSON body with challenge_token (64-character hex string) and sid.

Example request

curl -X POST https://api.agentsignet.com/agents/SID-0x7a3f8b2c1d4e5f6a/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "https://my-agent.example.com/signet/callback"
  }'

Example response (202)

{
  "message": "Verification challenge sent to callback URL",
  "expires_in": 600
}

Errors

| Status | Response | Cause | |--------|----------|-------| | 400 | {"error": "callbackUrl is required"} | Missing callback URL | | 400 | {"error": "callbackUrl must use HTTPS"} | Non-HTTPS URL | | 400 | {"error": "callbackUrl must not resolve to a private address"} | SSRF protection | | 401 | {"error": "Invalid API key"} | Authentication failure | | 403 | {"error": "Forbidden: you do not own this agent"} | Not the agent's owner | | 404 | {"error": "Agent not found"} | SID does not exist | | 429 | {"error": "Too many verification attempts"} | Rate limited (3/hr) |

POST /agents/:sid/verify/confirm

Confirm a verification challenge by returning the challenge token. On success, the agent's identity level is upgraded to 1 (Callback-Verified).

Authentication: Required (must be the agent's owner)

Path parameters

| Parameter | Type | Description | |-----------|--------|-----------------------| | sid | string | The agent's Signet ID |

Request body

| Field | Type | Required | Description | |-------------------|--------|----------|------------------------------------------| | challenge_token | string | Yes | The 64-character hex token received at your callback URL |

Example request

curl -X POST https://api.agentsignet.com/agents/SID-0x7a3f8b2c1d4e5f6a/verify/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge_token": "a1b2c3d4e5f6..."
  }'

Example response (200)

{
  "message": "Identity verified successfully",
  "identity_level": 1,
  "identity_label": "Callback-Verified"
}

Errors

| Status | Response | Cause | |--------|----------|-------| | 400 | {"error": "challenge_token is required"} | Missing token | | 400 | {"error": "Invalid or expired challenge token"} | Wrong token, expired (10 min), or already used | | 401 | {"error": "Invalid API key"} | Authentication failure | | 403 | {"error": "Forbidden: you do not own this agent"} | Not the agent's owner | | 404 | {"error": "Agent not found"} | SID does not exist |

Error format

All error responses use a simple JSON object:

{
  "error": "Description of what went wrong"
}

Common errors

| Status | Example error | Cause | |--------|----------------------------------------------|------------------------------------| | 400 | "Missing required fields: name, modelProvider, modelName" | Missing required field | | 400 | "Invalid SID format. Expected: SID-0x[16 hex chars]" | Malformed SID | | 401 | "Missing or invalid Authorization header..." | No auth header | | 401 | "Invalid API key" | Key not found | | 403 | "Forbidden: you do not own this agent" | Config update by non-owner | | 404 | "Agent not found" | SID does not exist | | 409 | "An application with this email already exists." | Duplicate application | | 429 | "Too many requests. Please try again later." | Rate limited |