Elydora Docs
Docs/API Reference/Agents

Agents

Manage AI agent identities. Each agent is identified by a unique ID and an Ed25519 public key used to verify operation signatures.

Register Agent

POST
/v1/agents/register
Register a new agent with its Ed25519 public key.
Auth: integration_engineer

Request Body

FieldTypeRequiredDescription
agent_idstringYesUnique agent identifier (e.g. agent_underwriter)
display_namestringNoHuman-readable agent label (defaults to agent_id)
responsible_entitystringNoContact or team responsible for this agent
integration_typestringNoIntegration type (default: "sdk")
keysarrayYesArray of signing keys, each with kid, public_key, and algorithm

Example Request

bash
curl -X POST https://api.elydora.com/v1/agents/register \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_underwriter",
    "display_name": "Loan Underwriter v2",
    "responsible_entity": "underwriting-team@acme.com",
    "keys": [
      {
        "kid": "agent_underwriter-key-v1",
        "public_key": "MCowBQYDK2VwAyEA...",
        "algorithm": "ed25519"
      }
    ]
  }'

Response

json
{
  "agent": {
    "agent_id": "agent_underwriter",
    "org_id": "org_acme",
    "display_name": "Loan Underwriter v2",
    "responsible_entity": "underwriting-team@acme.com",
    "integration_type": "sdk",
    "status": "active",
    "created_at": 1736935800000,
    "updated_at": 1736935800000
  },
  "keys": [
    {
      "kid": "agent_underwriter-key-v1",
      "agent_id": "agent_underwriter",
      "public_key": "MCowBQYDK2VwAyEA...",
      "algorithm": "ed25519",
      "status": "active",
      "created_at": 1736935800000,
      "retired_at": null
    }
  ]
}

List Agents

GET
/v1/agents
List all agents in the organization.
Auth: readonly_investigator

Example Request

bash
curl https://api.elydora.com/v1/agents \
  -H "Authorization: Bearer <token>"

Response

json
{
  "agents": [
    {
      "agent_id": "agent_underwriter",
      "org_id": "org_acme",
      "display_name": "Loan Underwriter v2",
      "responsible_entity": "underwriting-team@acme.com",
      "integration_type": "sdk",
      "status": "active",
      "created_at": 1736935800000,
      "updated_at": 1736935800000
    }
  ]
}

Get Agent

GET
/v1/agents/:agent_id
Retrieve agent details including status and key information.
Auth: readonly_investigator

Path Parameters

FieldTypeRequiredDescription
agent_idstringYesThe agent's unique identifier

Response

json
{
  "agent": {
    "agent_id": "agent_underwriter",
    "org_id": "org_acme",
    "display_name": "Loan Underwriter v2",
    "responsible_entity": "underwriting-team@acme.com",
    "integration_type": "sdk",
    "status": "active",
    "created_at": 1736935800000,
    "updated_at": 1736935800000
  },
  "keys": [
    {
      "kid": "agent_underwriter-key-v1",
      "agent_id": "agent_underwriter",
      "public_key": "MCowBQYDK2VwAyEA...",
      "algorithm": "ed25519",
      "status": "active",
      "created_at": 1736935800000,
      "retired_at": null
    }
  ]
}

Update Agent

PATCH
/v1/agents/:agent_id
Update an agent's integration type.
Auth: integration_engineer

Path Parameters

FieldTypeRequiredDescription
agent_idstringYesThe agent's unique identifier

Request Body

FieldTypeRequiredDescription
integration_typestringYesNew integration type. Must be one of: claudecode, cursor, gemini, kirocli, kiroide, opencode, copilot, letta, codex, kimi, enterprise, gui, other

Example Request

bash
curl -X PATCH https://api.elydora.com/v1/agents/agent_underwriter \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "integration_type": "claudecode" }'

Response

json
{
  "agent": {
    "agent_id": "agent_underwriter",
    "org_id": "org_acme",
    "display_name": "Loan Underwriter v2",
    "responsible_entity": "underwriting-team@acme.com",
    "integration_type": "claudecode",
    "status": "active",
    "created_at": 1736935800000,
    "updated_at": 1740700800000
  }
}

Delete Agent

DELETE
/v1/agents/:agent_id
Permanently delete an agent.
Auth: security_admin

Example Request

bash
curl -X DELETE https://api.elydora.com/v1/agents/agent_underwriter \
  -H "Authorization: Bearer <token>"

Response

json
{
  "deleted": true
}

Freeze Agent

POST
/v1/agents/:agent_id/freeze
Temporarily suspend an agent. Frozen agents cannot submit operations.
Auth: security_admin

Freezing an agent is reversible. The agent's key and history are preserved, but new operation submissions will be rejected with AGENT_FROZEN.

Request Body

FieldTypeRequiredDescription
reasonstringYesReason for freezing the agent

Example Request

bash
curl -X POST https://api.elydora.com/v1/agents/agent_underwriter/freeze \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Suspected anomalous activity" }'

Response

json
{
  "agent": {
    "agent_id": "agent_underwriter",
    "org_id": "org_acme",
    "display_name": "Loan Underwriter v2",
    "responsible_entity": "underwriting-team@acme.com",
    "integration_type": "sdk",
    "status": "frozen",
    "created_at": 1736935800000,
    "updated_at": 1740754800000
  }
}

Unfreeze Agent

POST
/v1/agents/:agent_id/unfreeze
Reactivate a frozen agent, restoring its ability to submit operations.
Auth: security_admin

Unfreezing reverses a previous freeze. The agent returns to active status and can resume submitting operations. Only agents in frozen status can be unfrozen — revoked agents cannot be reactivated.

Request Body

FieldTypeRequiredDescription
reasonstringYesReason for unfreezing the agent

Example Request

bash
curl -X POST https://api.elydora.com/v1/agents/agent_underwriter/unfreeze \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Investigation complete, agent cleared" }'

Response

json
{
  "agent": {
    "agent_id": "agent_underwriter",
    "org_id": "org_acme",
    "display_name": "Loan Underwriter v2",
    "responsible_entity": "underwriting-team@acme.com",
    "integration_type": "sdk",
    "status": "active",
    "created_at": 1736935800000,
    "updated_at": 1740758400000
  }
}

Revoke Agent Key

POST
/v1/agents/:agent_id/revoke
Permanently revoke a specific agent key. This action is irreversible.
Auth: security_admin

Revoking a key permanently invalidates the specified signing key. Past operations signed by the key remain verifiable, but new operations using that key will be rejected with KEY_REVOKED.

Request Body

FieldTypeRequiredDescription
kidstringYesKey ID of the key to revoke
reasonstringYesReason for revoking the key

Example Request

bash
curl -X POST https://api.elydora.com/v1/agents/agent_underwriter/revoke \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "kid": "kid_abc123", "reason": "Key compromised" }'

Response

json
{
  "key": {
    "kid": "kid_abc123",
    "agent_id": "agent_underwriter",
    "public_key": "MCowBQYDK2VwAyEA...",
    "algorithm": "ed25519",
    "status": "revoked",
    "created_at": 1736935800000,
    "retired_at": 1740755400000
  }
}