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 /register

Register a new agent and receive a Signet ID (SID). This creates a permanent trust profile for the agent.

Authentication: Required

Request body

| Field | Type | Required | Description | |----------------|----------|----------|--------------------------------------------------| | name | string | Yes | Human-readable agent name | | description | string | No | Brief description of the agent's purpose | | model | string | No | LLM backbone (e.g., gpt-4o, claude-sonnet) | | capabilities | string[] | No | List of capability tags |

Example request

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

Response

| Field | Type | Description | |-----------------|--------|-------------------------------------------| | sid | string | The agent's unique Signet ID | | name | string | The registered agent name | | created_at | string | ISO 8601 timestamp of registration | | status | string | Agent status (active) | | initial_score | number | Starting score (always 500) |

Example response

{
  "sid": "SID-0x7a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c",
  "name": "my-trading-agent",
  "created_at": "2025-06-15T10:30:00Z",
  "status": "active",
  "initial_score": 500
}

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-0x7a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c \
  -H "Authorization: Bearer sk_signet_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Response

| Field | Type | Description | |------------------|--------|-------------------------------------------------| | sid | string | The agent's Signet ID | | score | number | Composite score (0 -- 1000) | | confidence | string | low, medium, or high | | recommendation | string | clear, review, or caution | | dimensions | object | Individual dimension scores (0.0 -- 1.0 each) | | updated_at | string | ISO 8601 timestamp of last score update |

Example response

{
  "sid": "SID-0x7a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c",
  "score": 782,
  "confidence": "high",
  "recommendation": "clear",
  "dimensions": {
    "reliability": 0.85,
    "quality": 0.79,
    "financial": 0.91,
    "security": 0.72,
    "stability": 0.68
  },
  "updated_at": "2025-07-20T14:12:00Z"
}

GET /score/:sid/public

Retrieve a limited public score summary for an agent. This endpoint does not require authentication and returns fewer fields than the full score endpoint.

Authentication: Not required

Path parameters

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

Example request

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

Response

| Field | Type | Description | |------------------|--------|-------------------------------------------------| | sid | string | The agent's Signet ID | | score | number | Composite score (0 -- 1000) | | confidence | string | low, medium, or high | | recommendation | string | clear, review, or caution | | updated_at | string | ISO 8601 timestamp of last score update |

Example response

{
  "sid": "SID-0x7a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c",
  "score": 782,
  "confidence": "high",
  "recommendation": "clear",
  "updated_at": "2025-07-20T14:12:00Z"
}

GET /report/:sid

Retrieve a comprehensive trust report for an agent, including operator data, configuration history, and score change logs.

Authentication: Required

Path parameters

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

Example request

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

Response

| Field | Type | Description | |-----------------|----------|----------------------------------------------------| | sid | string | The agent's Signet ID | | name | string | Registered agent name | | score | number | Composite score (0 -- 1000) | | confidence | string | low, medium, or high | | recommendation| string | clear, review, or caution | | dimensions | object | Individual dimension scores (0.0 -- 1.0 each) | | operator | object | Operator score, history length, and agent count | | config | object | Current model, version, and last config change | | score_history | array | Recent score changes with timestamps and reasons | | created_at | string | ISO 8601 timestamp of agent registration | | updated_at | string | ISO 8601 timestamp of last score update |

Example response

{
  "sid": "SID-0x7a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c",
  "name": "my-trading-agent",
  "score": 782,
  "confidence": "high",
  "recommendation": "clear",
  "dimensions": {
    "reliability": 0.85,
    "quality": 0.79,
    "financial": 0.91,
    "security": 0.72,
    "stability": 0.68
  },
  "operator": {
    "score": 891,
    "history": "2y",
    "agents_operated": 5
  },
  "config": {
    "model": "gpt-4o",
    "version": "2.1.0",
    "last_change": "2025-07-10T08:00:00Z"
  },
  "score_history": [
    {
      "score": 760,
      "timestamp": "2025-07-10T08:00:00Z",
      "reason": "config_change_decay"
    },
    {
      "score": 782,
      "timestamp": "2025-07-20T14:12:00Z",
      "reason": "transaction_update"
    }
  ],
  "created_at": "2025-06-15T10:30:00Z",
  "updated_at": "2025-07-20T14:12:00Z"
}

POST /waitlist

Submit an email address to join the Signet early access waitlist. This endpoint is publicly accessible and does not require authentication.

Authentication: Not required

Rate limit: 5 requests per minute per IP address

Request body

| Field | Type | Required | Description | |---------|--------|----------|--------------------------------------| | email | string | Yes | A valid email address | | role | string | No | One of operator, platform, developer, other |

Example request

curl -X POST https://api.agentsignet.com/waitlist \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "role": "platform"
  }'

Response

| Field | Type | Description | |-----------|--------|-------------------------------------| | success | boolean| Whether the submission was accepted | | message | string | Confirmation message |

Example response

{
  "success": true,
  "message": "You've been added to the waitlist. We'll be in touch soon."
}

Error format

All error responses follow a consistent format:

{
  "error": {
    "code": "not_found",
    "message": "No agent found with the provided SID."
  }
}

Common error codes

| Status | Code | Description | |--------|---------------------|------------------------------------------| | 400 | invalid_request | Malformed JSON or missing required field | | 401 | missing_api_key | No Authorization header provided | | 401 | invalid_api_key | Key is invalid or not found | | 404 | not_found | SID does not exist | | 429 | rate_limited | Too many requests | | 500 | internal_error | Unexpected server error |

Know which agents to trust.

Join the waitlist for early access to Signet scores, reports, and the API.

No spam. Unsubscribe anytime.