Agents
Generated HTTP reference for the 4 operations the published OpenAPI document describes under agents.
3 min read
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
POST
https://api.codespar.dev/v1/agentsRegister 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 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"
}'const res = await fetch("https://api.codespar.dev/v1/agents", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"agent_id": "agt_0000000000000000",
"display_name": "Example",
"principal_ref": "string"
}),
});
const data = await res.json();Example response 201
{
"agent_did": "did:web:codespar.dev:org:agent",
"kid": "string",
"pubkey": "string",
"status": "active"
}POST /v1/agents/{agentId}/keys/rotate
POST
https://api.codespar.dev/v1/agents/{agentId}/keys/rotateMint 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 request
curl -X POST https://api.codespar.dev/v1/agents/{agentId}/keys/rotate \
-H "Authorization: Bearer $CODESPAR_API_KEY"const res = await fetch("https://api.codespar.dev/v1/agents/{agentId}/keys/rotate", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
},
});
const data = await res.json();Example response 201
{
"agent_did": "did:web:codespar.dev:org:agent",
"kid": "string",
"pubkey": "string",
"retired_kid": "string",
"status": "active"
}POST /v1/agents/{agentId}/keys/{kid}/revoke
POST
https://api.codespar.dev/v1/agents/{agentId}/keys/{kid}/revokeRevoke 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 request
curl -X POST https://api.codespar.dev/v1/agents/{agentId}/keys/{kid}/revoke \
-H "Authorization: Bearer $CODESPAR_API_KEY"const res = await fetch("https://api.codespar.dev/v1/agents/{agentId}/keys/{kid}/revoke", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
},
});
const data = await res.json();Example response 200
{
"kid": "string",
"status": "revoked",
"revoked_at": "string"
}POST /v1/agents/{did}/revoke
POST
https://api.codespar.dev/v1/agents/{did}/revokeRevoke 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 request
curl -X POST https://api.codespar.dev/v1/agents/{did}/revoke \
-H "Authorization: Bearer $CODESPAR_API_KEY"const res = await fetch("https://api.codespar.dev/v1/agents/{did}/revoke", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
},
});
const data = await res.json();Example response 200
{
"did": "did:web:codespar.dev:org:agent",
"status": "revoked",
"revoked_at": "string",
"revoked_kids": [
"string"
],
"limits": {
"stops": [
"string"
],
"does_not_stop": "string",
"issue": "string"
}
}