Kladoi

What is a Klados?

A klados (plural: kladoi) is an external service — typically a Cloudflare Worker — that performs a single, well-defined operation on Arke entities. Each klados declares:

What it accepts — Input types and cardinality (one entity or many)
What it produces — Output types and cardinality
What permissions it needs — Which entity/collection actions it requires
Where it lives — An HTTPS endpoint that receives job requests

Creating a Klados

POST /kladoi
Content-Type: application/json
Authorization: ApiKey <your-key>

{
  "label": "OCR Processor",
  "description": "Extracts text from scanned images using optical character recognition",
  "endpoint": "https://ocr-worker.your-domain.com",
  "actions_required": ["entity:view", "entity:update"],
  "accepts": {
    "types": ["file"],
    "cardinality": "one"
  },
  "produces": {
    "types": ["file"],
    "cardinality": "one"
  },
  "collection": "01KFNR0H0Q791Y1SMZWEQ09FGV"
}

The klados starts in development status. Before it can be invoked, you need to verify the endpoint and set status to active.

Input/Output Contracts

The accepts and produces fields define what a klados works with:

{
  "accepts": {
    "types": ["file", "document"],
    "cardinality": "one"
  },
  "produces": {
    "types": ["file"],
    "cardinality": "many"
  }
}

Field	Values	Description
`types`	string[]	Entity types this klados works with
`cardinality`	`"one"` or `"many"`	Whether it processes one entity or multiple

Cardinality determines how the invocation request is structured:

"one" — Request includes target_entity (single entity ID)
"many" — Request includes target_entities (array of entity IDs)

Input Schema

Optionally define a JSON Schema for additional parameters your klados accepts:

{
  "input_schema": {
    "type": "object",
    "properties": {
      "language": {
        "type": "string",
        "enum": ["en", "fr", "de", "es"],
        "default": "en"
      },
      "confidence_threshold": {
        "type": "number",
        "minimum": 0,
        "maximum": 1,
        "default": 0.8
      }
    }
  }
}

These parameters are passed to your worker in the input field of the job request.

Endpoint Verification

Before a klados can be set to active, you must prove you control the endpoint. Verification uses a two-phase flow:

Step 1: Request a verification token

POST /kladoi/{id}/verify
Content-Type: application/json
Authorization: ApiKey <your-key>

{
  "confirm": false
}

Response:

{
  "token": "vt_a1b2c3d4e5f6...",
  "klados_id": "01KFNR849AZNBWE9DYJRZR7PSA",
  "expires_at": "2025-01-15T11:00:00Z"
}

Step 2: Deploy the token

Add a /.well-known/arke-verification route to your worker that returns:

{
  "klados_id": "01KFNR849AZNBWE9DYJRZR7PSA",
  "token": "vt_a1b2c3d4e5f6..."
}

Step 3: Confirm verification

POST /kladoi/{id}/verify
Content-Type: application/json
Authorization: ApiKey <your-key>

{
  "confirm": true
}

The API fetches your /.well-known/arke-verification endpoint and checks the token matches. On success, the klados receives an endpoint_verified_at timestamp.

Step 4: Activate

PUT /kladoi/{id}
Content-Type: application/json
Authorization: ApiKey <your-key>

{
  "status": "active"
}

Only verified kladoi can be set to active. Only active kladoi can be invoked.

API Key Management

Each klados needs its own API key to authenticate with the Arke API during job execution.

Create a key

POST /kladoi/{id}/keys
Content-Type: application/json
Authorization: ApiKey <your-key>

{
  "label": "Production key"
}

Response:

{
  "key": "ak_a1b2c3d4e5f6...",
  "prefix": "a1b2c3d4",
  "label": "Production key"
}

The full key is only returned once at creation. Store it securely — you cannot retrieve it later.

Keys use the ak_ prefix (agent keys). Use Authorization: ApiKey ak_... when authenticating as the klados.

List keys

GET /kladoi/{id}/keys
Authorization: ApiKey <your-key>

Returns key metadata (prefix, label, created_at) without the actual key values.

Revoke a key

DELETE /kladoi/{id}/keys/{prefix}
Authorization: ApiKey <your-key>

Invoking a Klados

Preview (Phase 1)

POST /kladoi/{id}/invoke
Content-Type: application/json
Authorization: ApiKey <your-key>

{
  "target_entity": "01KFNR849AZNBWE9DYJRZR7PSA",
  "target_collection": "01KFNR0H0Q791Y1SMZWEQ09FGV",
  "confirm": false
}

Returns a preview of what permissions will be granted, without executing.

Execute (Phase 2)

POST /kladoi/{id}/invoke
Content-Type: application/json
Authorization: ApiKey <your-key>

{
  "target_entity": "01KFNR849AZNBWE9DYJRZR7PSA",
  "target_collection": "01KFNR0H0Q791Y1SMZWEQ09FGV",
  "confirm": true,
  "input": {
    "language": "en"
  },
  "expires_in": 3600
}

Response (202 Accepted):

{
  "job_id": "job_01KJ...",
  "job_collection": "01KJ...",
  "status": "accepted",
  "expires_at": "2025-01-15T11:00:00Z"
}

Parameter	Type	Default	Description
`target_entity`	string	—	Entity to process (for cardinality: one)
`target_entities`	string[]	—	Entities to process (for cardinality: many)
`target_collection`	string	—	Collection containing target entities
`input`	object	—	Optional parameters matching `input_schema`
`expires_in`	number	3600	Permission duration in seconds
`confirm`	boolean	false	Preview (false) or execute (true)

Batch Invocation

Process multiple entities through the same klados in parallel:

POST /kladoi/{id}/invoke/batch
Content-Type: application/json
Authorization: ApiKey <your-key>

{
  "target_collection": "01KFNR0H0Q791Y1SMZWEQ09FGV",
  "invocations": [
    { "target_entity": "01KFNR849AZNBWE9DYJRZR7PSA" },
    { "target_entity": "01KFNR849BZNBWE9DYJRZR7PSB", "input": { "language": "fr" } },
    { "target_entity": "01KFNR849CZNBWE9DYJRZR7PSC" }
  ],
  "input": {
    "confidence_threshold": 0.9
  },
  "confirm": true
}

Each invocation can include its own input that merges with the shared input. All invocations share a single job collection.

Reinvoking Failed Jobs

If a job fails, you can retry it from the original log entry:

POST /kladoi/{id}/reinvoke
Content-Type: application/json
Authorization: ApiKey <your-key>

{
  "log_id": "01KJ_FAILED_LOG...",
  "job_collection": "01KJ_JOB_COLLECTION...",
  "confirm": true
}

The reinvocation extracts the original request parameters from the failed log, generates a new job ID, and maintains an audit chain via parent_logs.

Permission Actions

Action	Description
`klados:create`	Create new kladoi
`klados:view`	View klados details
`klados:update`	Update klados configuration
`klados:invoke`	Trigger klados processing
`klados:manage`	Manage klados API keys

On this page