Agents API¶

The Agents API provides full lifecycle management for AI agents on the ARX platform. Agents are the primary resource in ARX -- they represent autonomous programs that interact with external systems through connectors, governed by policies, and tracked by the immutable audit trail.

All endpoints are scoped to the authenticated user's organization via Row-Level Security.

List Agents¶

Retrieves all agents for the authenticated user's organization.

• Method: GET
• Path: /v1/agents
• Required Role: Any authenticated user

Response¶

{
  "agents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "org_id": "org-uuid",
      "name": "triage-agent",
      "description": "Automated SOC triage agent for CrowdStrike detections",
      "owner_id": "user-uuid",
      "runtime": "docker",
      "image_uri": "registry.arxsec.io/org/triage-agent:v3",
      "status": "active",
      "version": 3,
      "declared_intent": { ... },
      "created_at": "2026-03-15T10:00:00Z",
      "updated_at": "2026-04-01T14:30:00Z"
    }
  ],
  "total": 1
}

Example¶

curl -X GET "https://api.arxsec.io/v1/agents" \
  -H "Authorization: Bearer {token}"

Get Agent¶

Retrieves a single agent by ID.

• Method: GET
• Path: /v1/agents/{agent_id}
• Required Role: Any authenticated user

Path Parameters¶

Response¶

Returns the full agent object. Returns 404 if the agent does not exist or belongs to a different organization.

Example¶

curl -X GET "https://api.arxsec.io/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {token}"

Create Agent¶

Creates a new agent in the inactive state.

• Method: POST
• Path: /v1/agents
• Required Role: admin or deployer

Request Body¶

Example¶

curl -X POST "https://api.arxsec.io/v1/agents" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "triage-agent",
    "description": "Automated SOC triage agent",
    "runtime": "docker"
  }'

Response¶

Returns the created agent object with status: "inactive" and HTTP status 201 Created.

Update Agent¶

Updates an existing agent's metadata.

• Method: PATCH
• Path: /v1/agents/{agent_id}
• Required Role: admin or deployer

Path Parameters¶

Request Body¶

All fields are optional. Only provided fields are updated.

Example¶

curl -X PATCH "https://api.arxsec.io/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated triage agent with Sentinel integration"
  }'

Response¶

Returns the updated agent object. Returns 400 if no fields are provided. Returns 404 if the agent is not found.

Deploy Agent¶

Deploys an agent to production. Creates a new version record and sets the agent status to active.

• Method: POST
• Path: /v1/agents/{agent_id}/deploy
• Required Role: admin or deployer

Path Parameters¶

Request Body¶

Example¶

curl -X POST "https://api.arxsec.io/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/deploy" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "image_uri": "registry.arxsec.io/org/triage-agent:v4",
    "notes": "Added Sentinel connector support"
  }'

Response¶

Returns the updated agent object with incremented version and status: "active". The deployment is audit-logged with version number and image URI.

Suspend Agent¶

Suspends a running agent. Sets the agent status to suspended.

• Method: POST
• Path: /v1/agents/{agent_id}/suspend
• Required Role: admin

Path Parameters¶

Example¶

curl -X POST "https://api.arxsec.io/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/suspend" \
  -H "Authorization: Bearer {token}"

Response¶

Returns the updated agent object with status: "suspended". Returns 404 if the agent is not found.

Set Declared Intent¶

Sets the declared intent manifest for an agent (INV-003). The intent manifest defines the systems, actions, and data types the agent is authorized to use. Behavioral drift detection compares actual behavior against this manifest.

• Method: PUT
• Path: /v1/agents/{agent_id}/intent
• Required Role: admin or deployer

Path Parameters¶

Request Body¶

The request body is the declared intent manifest. The schema is defined by the AgentDeclaredIntent model and includes permitted systems, actions, data types, and scope boundaries.

Example¶

curl -X PUT "https://api.arxsec.io/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/intent" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "permitted_connectors": ["crowdstrike", "jira"],
    "permitted_actions": ["detections:read", "issues:create"],
    "data_types": ["detection data", "issue data"],
    "description": "Read CrowdStrike detections and create Jira tickets for triage"
  }'

Response¶

Returns the updated agent object with the declared_intent, declared_intent_signed_by, and declared_intent_signed_at fields populated. Returns 404 if the agent is not found.

Rollback Agent¶

Rolls back an agent to a previous version.

• Method: POST
• Path: /v1/agents/{agent_id}/rollback
• Required Role: admin or deployer

Path Parameters¶

Query Parameters¶

Example¶

curl -X POST "https://api.arxsec.io/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/rollback?target_version=2" \
  -H "Authorization: Bearer {token}"

Response¶

Returns the updated agent object with the rolled-back version and status: "active". Returns 400 if no previous version exists. The rollback is audit-logged with from_version and to_version metadata.

List Agent Versions¶

Lists all deployment versions for an agent, ordered by version number descending.

• Method: GET
• Path: /v1/agents/{agent_id}/versions
• Required Role: Any authenticated user

Path Parameters¶

Example¶

curl -X GET "https://api.arxsec.io/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/versions" \
  -H "Authorization: Bearer {token}"

Response¶

{
  "versions": [
    {
      "id": "version-uuid",
      "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "version": 3,
      "image_uri": "registry.arxsec.io/org/triage-agent:v3",
      "config": { ... },
      "deployed_by": "user-uuid",
      "notes": "Added Sentinel connector support",
      "created_at": "2026-04-01T14:30:00Z"
    }
  ],
  "total": 3
}

Run Agent¶

Executes an agent's Docker container with resource limits and timeout enforcement. Captures stdout and stderr output.

• Method: POST
• Path: /v1/agents/{agent_id}/run
• Required Role: admin or deployer

Path Parameters¶

Preconditions¶

• The agent must have an image_uri configured (set via the deploy endpoint).
• The agent must not be in suspended status.

Example¶

curl -X POST "https://api.arxsec.io/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/run" \
  -H "Authorization: Bearer {token}"

Response¶

{
  "execution_id": "exec-uuid",
  "status": "success",
  "exit_code": 0,
  "duration_ms": 4523,
  "stdout": ["Processing 12 detections...", "Created 3 Jira tickets."],
  "stderr": []
}

Returns 400 if no Docker image is configured. Returns 403 if the agent is suspended. Resource limits (CPU, memory, timeout) are determined by the organization's plan tier. The execution is audit-logged with execution ID, exit code, duration, and output line counts.