Arke
ReferenceAPI Reference

Kladoi

Workflow action units - atomic operations with defined inputs/outputs

Create a klados

POST
/kladoi

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

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

Klados display name

Length1 <= length <= 200
endpoint*string

Klados service base URL

Formaturi
actions_required*array<>

Actions this klados requires on target collections

Items1 <= items
accepts*

What this klados accepts as input

produces*

What this klados produces as output

collection*string

Collection to place klados in

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

Klados description

Lengthlength <= 2000
input_schema?

JSON Schema for input validation

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://api.arke.institute/kladoi" \  -H "Content-Type: application/json" \  -d '{    "label": "PDF Text Extractor",    "endpoint": "https://pdf-extractor.example.com/v1",    "actions_required": [      "entity:view",      "entity:update",      "entity:create"    ],    "accepts": {      "types": [        "file/pdf",        "file/png"      ],      "cardinality": "one"    },    "produces": {      "types": [        "file/pdf",        "file/png"      ],      "cardinality": "one"    },    "collection": "string"  }'
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "klados",
  "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"
}
{
  "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 klados by ID

GET
/kladoi/{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://api.arke.institute/kladoi/01KDETYWYWM0MJVKM8DK3AEXPY"
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "klados",
  "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"
}
{
  "error": "Forbidden: You do not have permission to perform this action"
}
{
  "error": "Entity not found"
}

Update klados

PUT
/kladoi/{id}

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

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 klados display name

Length1 <= length <= 200
description?string

Updated klados description

Lengthlength <= 2000
endpoint?string

Updated klados service URL. Changing this clears endpoint_verified_at.

Formaturi
actions_required?array<>

Actions this klados requires on target collections

Items1 <= items
status?string

Klados status

Value in"development" | "active" | "disabled"
accepts?

Input/output contract specification for klados

produces?

Input/output contract specification for klados

input_schema?

Updated input schema

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://api.arke.institute/kladoi/01KDETYWYWM0MJVKM8DK3AEXPY" \  -H "Content-Type: application/json" \  -d '{    "expect_tip": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy"  }'
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "klados",
  "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"
}
{
  "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 a klados

POST
/kladoi/{id}/invoke

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

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_entity?string

Single entity to process (required when klados.accepts.cardinality = "one")

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

Multiple entities to process (required when klados.accepts.cardinality = "many")

Items1 <= items
target_collection*string

Collection for permission grant. Klados receives temporal permissions on this collection.

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 klados should write logs. If not provided, creates new 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 klados (validated against input_schema)

expires_in?integer

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

Default3600
Range60 <= value <= 86400
confirm?boolean

false = preview grants, true = execute klados

Defaultfalse
rhiza?

Rhiza context for workflow invocations

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.arke.institute/kladoi/01KDETYWYWM0MJVKM8DK3AEXPY/invoke" \  -H "Content-Type: application/json" \  -d '{    "target_collection": "string"  }'
{
  "status": "pending_confirmation",
  "message": "string",
  "grants": [
    {
      "klados": {
        "id": "string",
        "label": "string"
      },
      "actions": [
        "string"
      ],
      "role": "string",
      "already_granted": true,
      "expired": 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
}
{
  "status": "started",
  "job_id": "job_01JEXAMPLEID12345678901",
  "job_collection": "string",
  "klados_id": "string",
  "grants": [
    {
      "klados_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"
}

Verify klados endpoint ownership

POST
/kladoi/{id}/verify

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

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 verification token.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.arke.institute/kladoi/01KDETYWYWM0MJVKM8DK3AEXPY/verify" \  -H "Content-Type: application/json" \  -d '{}'
{
  "verification_token": "vt_abc123def456...",
  "klados_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"
}

Reinvoke a failed klados job

POST
/kladoi/{id}/reinvoke

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

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

log_id*string

Log file entity ID containing the failed invocation to retry

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

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

Default3600
Range60 <= value <= 86400

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.arke.institute/kladoi/01KDETYWYWM0MJVKM8DK3AEXPY/reinvoke" \  -H "Content-Type: application/json" \  -d '{    "log_id": "01JLOGFILE1234567890123456"  }'
{
  "accepted": true,
  "job_id": "job_01JEXAMPLEID12345678901",
  "original_log_id": "string",
  "error": "string",
  "retry_after": 0
}
{
  "accepted": true,
  "job_id": "job_01JEXAMPLEID12345678901",
  "original_log_id": "string",
  "error": "string",
  "retry_after": 0
}
{
  "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 klados

GET
/kladoi/{id}/keys

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

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://api.arke.institute/kladoi/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 klados

POST
/kladoi/{id}/keys

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

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://api.arke.institute/kladoi/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
/kladoi/{id}/keys/{prefix}

Authorization

AuthorizationBearer <token>

Supabase JWT token. Use Authorization: Bearer <jwt>. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys.

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://api.arke.institute/kladoi/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"
}

Graph

Previous Page

Permissions

Next Page