Arke
ReferenceAPI Reference

Rhizai

Workflow orchestration - DAGs of kladoi for multi-step pipelines

Create a rhiza workflow

POST
/rhizai

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

Rhiza display name

Length1 <= length <= 200
version*string

Semantic version

Length1 <= length <= 50
entry*string

Entry point step name (must exist as a key in flow)

Length1 <= length <= 100
flow*

Flow definition mapping step names to their klados references and handoff specifications. Step names are arbitrary strings that identify each step in the workflow.

collection*string

Collection to place rhiza in

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

Rhiza description

Lengthlength <= 2000
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/rhizai" \  -H "Content-Type: application/json" \  -d '{    "label": "Document Processing Pipeline",    "version": "1.0.0",    "entry": "extract",    "flow": {      "extract": {        "klados": {          "id": "01KKLADOSA12345678901234",          "type": "klados"        },        "then": {          "pass": "summarize"        }      },      "summarize": {        "klados": {          "id": "01KKLADOSB12345678901234",          "type": "klados"        },        "then": {          "done": true        }      }    },    "collection": "string"  }'
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "rhiza",
  "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 rhiza by ID

GET
/rhizai/{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/rhizai/01KDETYWYWM0MJVKM8DK3AEXPY"
{
  "id": "01KDETYWYWM0MJVKM8DK3AEXPY",
  "cid": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
  "type": "rhiza",
  "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 rhiza

PUT
/rhizai/{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 rhiza display name

Length1 <= length <= 200
description?string

Updated rhiza description

Lengthlength <= 2000
version?string

Updated semantic version

Length1 <= length <= 50
entry?string

Updated entry point step name (must exist as a key in flow)

Length1 <= length <= 100
flow?

Flow definition mapping step names to their klados references and handoff specifications. Step names are arbitrary strings that identify each step in the workflow.

status?string

Rhiza status

Value in"development" | "active" | "disabled"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

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

POST
/rhizai/{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 entry 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 entry klados.accepts.cardinality = "many")

Items1 <= items
target_collection*string

Collection for permission grant. All kladoi in workflow receive 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})$
input?

Input data for the workflow

expires_in?integer

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

Default3600
Range60 <= value <= 86400
confirm?boolean

false = preview grants, true = execute workflow

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.arke.institute/rhizai/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
    }
  ],
  "target": {
    "id": "string",
    "label": "string"
  },
  "expires_at": "2019-08-24T14:15:22Z",
  "kladoi_count": 0,
  "all_ready": true,
  "klados_issues": [
    {
      "id": "string",
      "reason": "string"
    }
  ]
}
{
  "status": "started",
  "job_id": "job_01JEXAMPLEID12345678901",
  "job_collection": "string",
  "rhiza_id": "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 workflow job status

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

Path Parameters

id*string

Rhiza 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 rhiza invocation

Length1 <= length

Response Body

application/json

application/json

curl -X GET "https://api.arke.institute/rhizai/string/jobs/job_01KFXPQ3ABCDEFGHIJKLMN/status"
{
  "job_id": "string",
  "rhiza_id": "string",
  "status": "pending",
  "progress": {
    "total": 0,
    "pending": 0,
    "running": 0,
    "done": 0,
    "error": 0
  },
  "current_kladoi": [
    "string"
  ],
  "errors": [
    {
      "klados_id": "string",
      "job_id": "string",
      "code": "string",
      "message": "string",
      "retryable": true
    }
  ],
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}
{
  "error": "Entity not found"
}

Resume failed workflow

POST
/rhizai/{id}/jobs/{job_id}/resume

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

Rhiza 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 rhiza invocation

Length1 <= length

Request Body

application/json

error_codes?array<>

Only resume jobs with these error codes (all retryable if not specified)

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.arke.institute/rhizai/string/jobs/job_01KFXPQ3ABCDEFGHIJKLMN/resume" \  -H "Content-Type: application/json" \  -d '{}'
{
  "resumed": 0,
  "skipped": 0,
  "jobs": [
    {
      "original_job_id": "string",
      "klados_id": "string",
      "new_job_id": "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"
}

Query

Previous Page

Search

Next Page