Arke
ReferenceAPI Reference

Agents

Agent management and invocation

Create an agent

POST
/agents

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Request Body

application/json

note?string

Optional note describing this change

id?string

Custom entity ID (generated if not provided)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$
label*string

Agent display name

Length1 <= length <= 200
endpoint*string

Agent service base URL

Formaturi
actions_required*array<>

Actions this agent requires on target collections

Items1 <= items
collection*string

Collection to place agent in

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$
description?string

Agent description

Lengthlength <= 2000
uses_agents?array<>

Sub-agents this orchestrator delegates work to. Only provide the sub-agent ID (pi) - their permissions are fetched dynamically at invocation time. Warnings are returned if any referenced sub-agents do not exist or are disabled.

input_schema?

JSON Schema for input validation

output_schema?

JSON Schema for output description

properties?

Additional properties to store

relationships?array<>

Relationships to create

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/agents" \  -H "Content-Type: application/json" \  -d '{    "label": "OCR Processor",    "endpoint": "https://ocr.example.com/v1",    "actions_required": [      "entity:view",      "entity:update",      "file:create"    ],    "collection": "string"  }'
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "agent",
  "properties": {
    "label": "The Pequod's Archive",
    "description": "A collection of whaling documents"
  },
  "relationships": [
    {
      "predicate": "crew",
      "peer": "01KDETYWYWM0MJVKM8DK3AEXPY",
      "peer_type": "collection"
    }
  ],
  "ver": 1,
  "created_at": "2025-12-26T12:00:00.000Z",
  "ts": 1735214400000,
  "edited_by": {
    "user_id": "01JCAPTAINAHAB000000000000",
    "user_label": "Captain Ahab",
    "method": "manual"
  },
  "prev_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "warnings": [
    {
      "sub_agent_id": "string",
      "reason": "not_found",
      "message": "string"
    }
  ]
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}
{
  "error": "Unauthorized: Missing or invalid authentication token"
}
{
  "error": "Forbidden: You do not have permission to perform this action"
}
{
  "error": "Entity not found"
}

Get agent by ID

GET
/agents/{id}

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Response Body

application/json

application/json

application/json

curl -X GET "https://arke-v1.arke.institute/agents/01KDETYWYWM0MJVKM8DK3AEXPY"
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "agent",
  "properties": {
    "label": "The Pequod's Archive",
    "description": "A collection of whaling documents"
  },
  "relationships": [
    {
      "predicate": "crew",
      "peer": "01KDETYWYWM0MJVKM8DK3AEXPY",
      "peer_type": "collection"
    }
  ],
  "ver": 1,
  "created_at": "2025-12-26T12:00:00.000Z",
  "ts": 1735214400000,
  "edited_by": {
    "user_id": "01JCAPTAINAHAB000000000000",
    "user_label": "Captain Ahab",
    "method": "manual"
  },
  "prev_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "warnings": [
    {
      "sub_agent_id": "string",
      "reason": "not_found",
      "message": "string"
    }
  ]
}
{
  "error": "Forbidden: You do not have permission to perform this action"
}
{
  "error": "Entity not found"
}

Update agent

PUT
/agents/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Request Body

application/json

expect_tip*string

Current tip CID for CAS validation. Request fails with 409 if this does not match.

Length1 <= length
note?string

Optional note describing this change

properties?

Properties to add or update (deep merged)

properties_remove?array<>|

Properties to remove. Use string[] for top-level keys (e.g., ["old_field"]), or nested objects for deep removal (e.g., { config: { options: ["debug"] } }). Dot notation like "config.options.debug" is NOT supported.

relationships_add?array<>

Relationships to add or update (upsert semantics)

relationships_remove?array<>

Relationships to remove

label?string

Updated agent display name

Length1 <= length <= 200
description?string

Updated agent description

Lengthlength <= 2000
endpoint?string

Updated agent service URL

Formaturi
actions_required?array<>

Actions this agent requires on target collections

Items1 <= items
status?string

Agent status

Value in"development" | "active" | "disabled"
uses_agents?array<>

Updated sub-agent references. Only provide sub-agent IDs (pi) - their permissions are fetched dynamically at invocation time.

input_schema?

Updated input schema

output_schema?

Updated output schema

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://arke-v1.arke.institute/agents/01KDETYWYWM0MJVKM8DK3AEXPY" \  -H "Content-Type: application/json" \  -d '{    "expect_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"  }'
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "agent",
  "properties": {
    "label": "The Pequod's Archive",
    "description": "A collection of whaling documents"
  },
  "relationships": [
    {
      "predicate": "crew",
      "peer": "01KDETYWYWM0MJVKM8DK3AEXPY",
      "peer_type": "collection"
    }
  ],
  "ver": 1,
  "created_at": "2025-12-26T12:00:00.000Z",
  "ts": 1735214400000,
  "edited_by": {
    "user_id": "01JCAPTAINAHAB000000000000",
    "user_label": "Captain Ahab",
    "method": "manual"
  },
  "prev_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "warnings": [
    {
      "sub_agent_id": "string",
      "reason": "not_found",
      "message": "string"
    }
  ]
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}
{
  "error": "Unauthorized: Missing or invalid authentication token"
}
{
  "error": "Forbidden: You do not have permission to perform this action"
}
{
  "error": "Entity not found"
}
{
  "error": "Conflict: entity was modified",
  "details": {
    "expected": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
    "actual": "bafyreinewabc123456789defghijklmnopqrstuvwxyz"
  }
}

Invoke an agent

POST
/agents/{id}/invoke

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Request Body

application/json

target*string

Collection ID to grant the agent access to. All agent permissions are collection-scoped.

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$
job_collection?string

Job collection where agent should write logs. If not provided, creates new root collection.

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$
input?

Input data for the agent (validated against agent input_schema)

expires_in?integer

Permission duration in seconds (60-86400, default: 3600)

Default3600
Range60 <= value <= 86400
confirm?boolean

false = preview grants, true = execute agent

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/agents/01KDETYWYWM0MJVKM8DK3AEXPY/invoke" \  -H "Content-Type: application/json" \  -d '{    "target": "string"  }'
{
  "status": "pending_confirmation",
  "message": "string",
  "grants": [
    {
      "agent": {
        "id": "string",
        "label": "string"
      },
      "actions": [
        "string"
      ],
      "role": "string",
      "already_granted": true,
      "expired": true,
      "missing_actions": true,
      "current_expires_at": "2019-08-24T14:15:22Z"
    }
  ],
  "target": {
    "id": "string",
    "label": "string"
  },
  "expires_at": "2019-08-24T14:15:22Z",
  "can_proceed": true,
  "grants_needed": true,
  "warnings": [
    {
      "sub_agent_id": "string",
      "parent_agent_id": "string",
      "reason": "not_found",
      "message": "string"
    }
  ]
}
{
  "status": "started",
  "job_id": "job_01JEXAMPLEID12345678901",
  "job_collection": "string",
  "grants": [
    {
      "agent_id": "string",
      "role": "string",
      "expires_at": "2019-08-24T14:15:22Z",
      "was_update": true
    }
  ],
  "target_cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "expires_at": "2019-08-24T14:15:22Z"
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}
{
  "error": "Unauthorized: Missing or invalid authentication token"
}
{
  "error": "Forbidden: You do not have permission to perform this action"
}
{
  "error": "Entity not found"
}

List API keys for agent

GET
/agents/{id}/keys

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://arke-v1.arke.institute/agents/01KDETYWYWM0MJVKM8DK3AEXPY/keys"
{
  "keys": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "prefix": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z",
      "last_used_at": "2019-08-24T14:15:22Z",
      "label": "string"
    }
  ]
}
{
  "error": "Unauthorized: Missing or invalid authentication token"
}
{
  "error": "Forbidden: You do not have permission to perform this action"
}
{
  "error": "Entity not found"
}

Create API key for agent

POST
/agents/{id}/keys

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Request Body

application/json

label?string

Human-readable label for the key

Lengthlength <= 100
expires_in_days?integer

Key expiration in days (1-365, default: 365)

Default365
Range1 <= value <= 365

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/agents/01KDETYWYWM0MJVKM8DK3AEXPY/keys" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "key": "ak_abc123...",
  "prefix": "ak_abc1",
  "created_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "label": "string"
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}
{
  "error": "Unauthorized: Missing or invalid authentication token"
}
{
  "error": "Forbidden: You do not have permission to perform this action"
}
{
  "error": "Entity not found"
}

Revoke API key

DELETE
/agents/{id}/keys/{prefix}

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$
prefix*string

API key prefix (e.g., ak_xKj9)

Length4 <= length <= 12

Response Body

application/json

application/json

application/json

curl -X DELETE "https://arke-v1.arke.institute/agents/01KDETYWYWM0MJVKM8DK3AEXPY/keys/ak_xKj9"
Empty
{
  "error": "Unauthorized: Missing or invalid authentication token"
}
{
  "error": "Forbidden: You do not have permission to perform this action"
}
{
  "error": "Entity not found"
}

Verify agent endpoint ownership

POST
/agents/{id}/verify

Authorization

bearerAuth
AuthorizationBearer <token>

Supabase JWT token

In: header

Path Parameters

id*string

Entity ID (ULID)

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$

Request Body

application/json

confirm?boolean

Set to true to perform verification. Omit or false to generate/get verification token.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://arke-v1.arke.institute/agents/01KDETYWYWM0MJVKM8DK3AEXPY/verify" \  -H "Content-Type: application/json" \  -d '{}'
{
  "verification_token": "vt_abc123def456...",
  "agent_id": "string",
  "endpoint": "http://example.com",
  "instructions": "string",
  "expires_at": "2019-08-24T14:15:22Z"
}
{
  "error": "Validation failed",
  "details": {
    "issues": [
      {
        "path": [
          "properties",
          "label"
        ],
        "message": "Required"
      }
    ]
  }
}
{
  "error": "Unauthorized: Missing or invalid authentication token"
}
{
  "error": "Forbidden: You do not have permission to perform this action"
}
{
  "error": "Entity not found"
}

Get job status from agent

GET
/agents/{id}/jobs/{job_id}/status

Path Parameters

id*string

Agent entity ID

Match^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$
job_id*string

Job ID returned from agent invocation (e.g., job_01KFX...)

Length1 <= length

Query Parameters

detail?string

Include detailed sub-job information (orchestrators/workflows only)

Value in"full"
errors?integer

Include last N errors in response (orchestrators only)

Range0 <= value <= 100

Response Body

application/json

application/json

application/json

curl -X GET "https://arke-v1.arke.institute/agents/string/jobs/job_01KFXPQ3ABCDEFGHIJKLMN/status"
{
  "job_id": "job_01KFXPQ3ABCDEFGHIJKLMN",
  "status": "running",
  "progress": {
    "total": 10,
    "pending": 3,
    "dispatched": 2,
    "done": 4,
    "error": 1
  },
  "started_at": "2026-01-26T17:48:15.000Z",
  "completed_at": "2026-01-26T17:49:30.000Z",
  "updated_at": "2026-01-26T17:49:27.000Z",
  "result": {
    "property1": null,
    "property2": null
  },
  "error": {
    "code": "TIMEOUT",
    "message": "Request timed out after 30 seconds"
  }
}
{
  "error": "Entity not found"
}
{
  "error": "Failed to reach agent: Connection refused"
}

Attestation

Permanent attestation of entity versions to Arweave for independent verification.

Auth

Next Page