Agents API

GET/api/agents/cp-public-key

public accessno bearer auth required

Return the CP's Ed25519 public key as base64.

Auth posture

Unauthenticated — intentionally. A public key is not a secret; any agent (or observer) may fetch it. Agents use this to pin the CP public key for verifying [VerifiedLiveContext] grants. This endpoint is mounted via agent_routes(), which sits OUTSIDE the human auth_middleware layer in main.rs, so no session or agent-token is required.

Returns 503 if the CP signing key was not initialised at startup (e.g. the key file was unreadable and the server continued in degraded mode).

Permissions

HTTP request

GET https://<your-host>/api/agents/cp-public-key

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  'https://<your-host>/api/agents/cp-public-key'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "public_key": null,
  "protocol_version": null
}

GET/api/agents/openapi.json

public accessno bearer auth required

Thin handler wrapping [openapi_document] for GET /api/agents/openapi.json.

Permissions

HTTP request

GET https://<your-host>/api/agents/openapi.json

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  'https://<your-host>/api/agents/openapi.json'

POST/api/agents/register

public accessno bearer auth required

Enrolls a new agent in 'pending' status.

Generates a bearer token, stores its SHA-256 hash, and returns the plaintext token ONCE. A pending agent cannot poll for jobs until an admin approves it.

Permissions

HTTP request

POST https://<your-host>/api/agents/register

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: RegisterBody.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

200 response headers

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-ryuki-protocol-version: 2' \
  --data '{"enrollment_challenge_id":"<uuid>","enrollment_challenge":"<string>","agent_id":"<string>","platform":"<string>","capabilities":{},"public_key":"<string>","enrollment_proof":"<string>"}' \
  'https://<your-host>/api/agents/register'

POST/api/agents/{agent_id}/heartbeat

agent access

Heartbeat.

Permissions

HTTP request

POST https://<your-host>/api/agents/{agent_id}/heartbeat

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: AgentHeartbeat.

Response

200 response body

Structure: AgentHeartbeatResponse.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer rya_<agent-token>' \
  --header 'Content-Type: application/json' \
  --header 'x-ryuki-protocol-version: 2' \
  --data '{}' \
  'https://<your-host>/api/agents/<agent_id>/heartbeat'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "agent_id": "<string>",
  "last_seen_at": {},
  "lease_deadline": {}
}

GET/api/agents/{agent_id}/jobs

agent access

Poll job.

Permissions

HTTP request

GET https://<your-host>/api/agents/{agent_id}/jobs

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

For 200, the known response body type is Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer rya_<agent-token>' \
  --header 'x-ryuki-protocol-version: 2' \
  'https://<your-host>/api/agents/<agent_id>/jobs'

POST/api/agents/{agent_id}/jobs/{job_id}/ack

agent access

Transitions Leased → Running.

The caller must supply the fencing_token and attempt_id that match the current lease. A mismatch returns 409.

Permissions

HTTP request

POST https://<your-host>/api/agents/{agent_id}/jobs/{job_id}/ack

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: AckBody.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer rya_<agent-token>' \
  --header 'Content-Type: application/json' \
  --header 'x-ryuki-protocol-version: 2' \
  --data '{"attempt_id":"<uuid>","fencing_token":"<string>"}' \
  'https://<your-host>/api/agents/<agent_id>/jobs/<job_id>/ack'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "job_id": null,
  "status": "<string>"
}

POST/api/agents/{agent_id}/jobs/{job_id}/result

agent access

Verifies and records the signed JobResult from an agent.

The full 9-step verifier runs FAIL-CLOSED: every check that fails returns 4xx and mutates nothing. The terminal UPDATE is a single atomic conditional statement guarded on (id, attempt_id, lease_generation, status IN ('Leased','Running'), unexpired database-clock lease). A repeat POST with the same (job_id, attempt_id, result_id) returns idempotent 200.

Permissions

HTTP request

POST https://<your-host>/api/agents/{agent_id}/jobs/{job_id}/result

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: ResultBody.

Response

For 200, the known response body type is serde_json::Value. Its field schema is unavailable, so no JSON shape is inferred.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer rya_<agent-token>' \
  --header 'Content-Type: application/json' \
  --header 'x-ryuki-protocol-version: 2' \
  --data '{"job_result":{}}' \
  'https://<your-host>/api/agents/<agent_id>/jobs/<job_id>/result'