Agents
Generated HTTP reference for the 4 operations the published OpenAPI document describes under agents.
Agents
This page is generated from the published OpenAPI document. It is complete with respect to that document and says nothing about surfaces the document does not describe yet. See what is generated here for what that means.
Base URL: https://api.codespar.dev
Every operation below requires a Bearer token. See Authentication.
POST /v1/agents
Register an agent identity and mint its first signing key
Request body
| Field | Type | Required | Description |
|---|---|---|---|
agent_id | string | yes | — |
display_name | string | no | — |
principal_ref | string | yes | — |
Responses
| Status | Body | Description |
|---|---|---|
201 | object | OK |
400 | object | Bad Request — schema failure, or a DID segment outside the URL-safe alphabet. |
409 | object | Conflict — the handle or the derived DID is taken. |
Response 201
| Field | Type | Required | Description |
|---|---|---|---|
agent_did | string | yes | — |
kid | string | yes | \<did\>#\<n\>, where n is the key's ordinal. |
pubkey | string | yes | base64. |
status | "active" | yes | — |
Example response
{
"agent_did": "did:web:codespar.dev:org:agent",
"kid": "string",
"pubkey": "string",
"status": "active"
}Example request
curl -X POST https://api.codespar.dev/v1/agents \
-H "Authorization: Bearer $CODESPAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agt_0000000000000000",
"display_name": "Example",
"principal_ref": "string"
}'POST /v1/agents/{agentId}/keys/rotate
Mint a new signing key and retire the current one
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
agentId | string | yes | — |
Responses
| Status | Body | Description |
|---|---|---|
201 | object | OK |
404 | object | Not Found — no such agent in this org. |
409 | object | Conflict — the agent has no active key to rotate. |
Response 201
| Field | Type | Required | Description |
|---|---|---|---|
agent_did | string | yes | — |
kid | string | yes | — |
pubkey | string | yes | base64. |
retired_kid | string | yes | — |
status | "active" | yes | — |
Example response
{
"agent_did": "did:web:codespar.dev:org:agent",
"kid": "string",
"pubkey": "string",
"retired_kid": "string",
"status": "active"
}Example request
curl -X POST https://api.codespar.dev/v1/agents/{agentId}/keys/rotate \
-H "Authorization: Bearer $CODESPAR_API_KEY"POST /v1/agents/{agentId}/keys/{kid}/revoke
Revoke one signing key
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
agentId | string | yes | — |
kid | string | yes | A full kid; the # must be sent as %23. |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
404 | object | Not Found — no such key on this org's agent. |
409 | object | Conflict — the key is already revoked. |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
kid | string | yes | — |
revoked_at | string | yes | — |
status | "revoked" | yes | — |
Example response
{
"kid": "string",
"status": "revoked",
"revoked_at": "string"
}Example request
curl -X POST https://api.codespar.dev/v1/agents/{agentId}/keys/{kid}/revoke \
-H "Authorization: Bearer $CODESPAR_API_KEY"POST /v1/agents/{did}/revoke
Revoke an agent identity
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
did | string | yes | — |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
404 | object | Not Found |
409 | object | Conflict — the agent is already revoked. |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
did | string | yes | — |
limits | object | yes | What this verb reaches and what it does not. Served with every 200 so the limit travels with the act. |
revoked_at | string | yes | — |
revoked_kids | array of string | yes | The signing keys the cascade revoked, in creation order. |
status | "revoked" | yes | — |
Example response
{
"did": "did:web:codespar.dev:org:agent",
"status": "revoked",
"revoked_at": "string",
"revoked_kids": [
"string"
],
"limits": {
"stops": [
"string"
],
"does_not_stop": "string",
"issue": "string"
}
}Example request
curl -X POST https://api.codespar.dev/v1/agents/{did}/revoke \
-H "Authorization: Bearer $CODESPAR_API_KEY"