API Reference¶

Complete API reference for capiscio-server. Interactive documentation is available at /swagger/index.html when the server is running.

Interactive Docs

For the best experience, use the Swagger UI when running locally.

Base URL¶

Environment	URL
Production	`https://registry.capisc.io`
Local	`http://localhost:8080`

Authentication¶

All /v1/* endpoints require authentication via API key:

Authorization: Bearer YOUR_API_KEY

Public endpoints (JWKS, DID resolution) do not require authentication.

Agents¶

List Agents¶

Retrieve all agents for the authenticated user.

GET /v1/agents

Response:

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Agent",
      "domain": "my-agent.example.com",
      "status": "enabled",
      "trustLevel": "2",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ]
}

Create Agent¶

Register a new agent.

POST /v1/agents
Content-Type: application/json

Request Body:

{
  "name": "My Agent",
  "domain": "my-agent.example.com",
  "description": "Production agent for task processing"
}

Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Agent",
    "domain": "my-agent.example.com",
    "status": "enabled",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "message": "Agent created successfully"
}

Get Agent¶

Retrieve a specific agent by ID.

GET /v1/agents/{id}

Parameters:

Name	Type	Description
`id`	path	Agent UUID

Update Agent¶

Update an existing agent.

PUT /v1/agents/{id}
Content-Type: application/json

Delete Agent¶

Delete an agent.

DELETE /v1/agents/{id}

Disable Agent¶

Disable an agent (prevents badge issuance).

POST /v1/agents/{id}/disable

Enable Agent¶

Re-enable a disabled agent.

POST /v1/agents/{id}/enable

Badges¶

Issue Badge¶

Issue a new trust badge for an agent. The badge is signed by the CapiscIO CA.

POST /v1/agents/{id}/badge
Content-Type: application/json

Request Body:

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

Field	Type	Required	Description
`domain`	string	Yes	Agent's verified domain
`trustLevel`	string	No	Trust level: "1", "2", "3", or "4" (default: "1")
`audience`	string[]	No	Allowed verifier URLs
`ttl`	int	No	Badge TTL in seconds (default: 300)

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
    "jti": "badge-uuid-here",
    "subject": "did:web:registry.capisc.io:agents:550e8400-e29b-41d4-a716-446655440000",
    "trustLevel": "2",
    "expiresAt": "2025-01-15T10:35:00Z"
  }
}

Error Responses:

Status	Description
400	Invalid request (missing domain, invalid trust level)
403	Agent is disabled
404	Agent not found

Verify Badge¶

Verify a trust badge token.

POST /v1/badges/verify
Content-Type: application/json

Request Body:

{
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
}

Response:

{
  "success": true,
  "data": {
    "valid": true,
    "claims": {
      "iss": "https://registry.capisc.io",
      "sub": "did:web:registry.capisc.io:agents:550e8400",
      "exp": 1705316100,
      "iat": 1705315800,
      "vc": {
        "credentialSubject": {
          "domain": "my-agent.example.com",
          "level": "2"
        }
      }
    }
  }
}

Get JWKS¶

Get the CA's public key set for badge verification. This endpoint is public.

GET /.well-known/jwks.json

Response:

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "base64url-encoded-public-key",
      "kid": "capiscio-ca-1705315800",
      "alg": "EdDSA",
      "use": "sig"
    }
  ]
}

DID Resolution¶

Get DID Document¶

Retrieve the W3C DID Document for an agent. Used for did:web resolution.

GET /agents/{id}/did.json

Response:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ],
  "id": "did:web:registry.capisc.io:agents:550e8400",
  "verificationMethod": [
    {
      "id": "did:web:registry.capisc.io:agents:550e8400#key-1",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:web:registry.capisc.io:agents:550e8400",
      "publicKeyMultibase": "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
    }
  ],
  "authentication": [
    "did:web:registry.capisc.io:agents:550e8400#key-1"
  ],
  "assertionMethod": [
    "did:web:registry.capisc.io:agents:550e8400#key-1"
  ]
}

API Keys¶

List API Keys¶

List all API keys for the authenticated user.

GET /v1/keys

Create API Key¶

Create a new API key.

POST /v1/keys
Content-Type: application/json

Request Body:

{
  "name": "Production Key"
}

Response:

{
  "success": true,
  "data": {
    "id": "key-uuid",
    "name": "Production Key",
    "key": "cpsc_live_abc123...",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "message": "API key created. Save it now - it won't be shown again."
}

Save Your Key

The full API key is only shown once at creation time. Store it securely.

Delete API Key¶

Delete an API key.

DELETE /v1/keys/{id}

Error Responses¶

All error responses follow this format:

{
  "error": "Error message here"
}

Status	Description
400	Bad Request - Invalid input
401	Unauthorized - Missing or invalid API key
403	Forbidden - Action not allowed
404	Not Found - Resource doesn't exist
500	Internal Server Error

Rate Limiting¶

API requests are rate-limited:

Endpoint	Limit
Badge issuance	100/min per agent
Other endpoints	1000/min per API key

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705315860

OpenAPI Specification¶

The full OpenAPI 2.0 (Swagger) specification is available at:

JSON: /swagger/doc.json
Interactive UI: /swagger/index.html

Download the spec:

curl https://registry.capisc.io/swagger/doc.json -o openapi.json