Building an Agent

Agent Service Requirements

An agent service is an HTTP endpoint that Arke calls. Your service needs to:

1. Accept POST requests from Arke with a signed payload
2. Verify the X-Arke-Signature header
3. Process the entity data
4. Call back to the Arke API with results

Request Format

Arke sends a POST request to your agent's endpoint:

{
  "entity_id": "01JENTITY...",
  "entity_type": "file",
  "action": "process",
  "callback_url": "https://arke-v1.arke.institute",
  "api_key": "ak_temporary_xxxxx"
}

The api_key is a temporary key with scoped permissions that expires after the job completes.

Verifying Signatures

Verify the X-Arke-Signature header using the Ed25519 public key from /.well-known/signing-key.

Calling Back

Use the temporary API key to read entities and write results:

# Read the entity
GET /entities/01JENTITY...
Authorization: ApiKey ak_temporary_xxxxx

# Update with results
PUT /entities/01JENTITY...
Authorization: ApiKey ak_temporary_xxxxx
{
  "expected_cid": "bafyreig...",
  "properties_merge": {
    "processing_status": "complete",
    "extracted_text": "..."
  }
}

Registration

Register your agent by creating an agent entity through the admin API. See the API Reference for the agent registration endpoints.