API docs by Redocly

CELLSTATE API (0.5.0)

Download OpenAPI specification:

URL: https://cellstate.batterypack.dev License: MIT

Cognitive Agent Long-term Intelligence, Behavioral Episodic Recall - Production Memory Framework for AI Agents

Trajectories

Task container management - top-level goals and sub-tasks

GET /api/v1/trajectories - List trajectories with filters

Authorizations:
api_keybearer_auth
query Parameters
status
string

Filter by trajectory status

agent_id
string

Filter by agent ID

parent_trajectory_id
string

Filter by parent trajectory ID

limit
integer <int32>

Maximum number of results

offset
integer <int32>

Offset for pagination

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "trajectories": [
    ]
}

POST /api/v1/trajectories - Create a new trajectory

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
agent_id
string or null <uuid>

Agent assigned to this trajectory

description
string or null

Optional description

metadata
object or null

Additional metadata

name
required
string

Name of the trajectory

parent_trajectory_id
string or null <uuid>

Parent trajectory ID (for sub-tasks)

Responses

Request samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "description": "string",
  • "metadata": { },
  • "name": "string",
  • "parent_trajectory_id": "d47865db-aef0-4c15-933a-0cc936082ee8"
}

Response samples

Content type
application/json
{
  • "_links": { },
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "metadata": { },
  • "name": "string",
  • "outcome": { },
  • "parent_trajectory_id": "d47865db-aef0-4c15-933a-0cc936082ee8",
  • "root_trajectory_id": "0f25abaa-7f0a-46dc-9cd9-abd889afef7f",
  • "status": "active",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "updated_at": "2019-08-24T14:15:22Z"
}

GET /api/v1/trajectories/{id} - Get trajectory by ID

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Trajectory ID

Responses

Response samples

Content type
application/json
{
  • "_links": { },
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "metadata": { },
  • "name": "string",
  • "outcome": { },
  • "parent_trajectory_id": "d47865db-aef0-4c15-933a-0cc936082ee8",
  • "root_trajectory_id": "0f25abaa-7f0a-46dc-9cd9-abd889afef7f",
  • "status": "active",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "updated_at": "2019-08-24T14:15:22Z"
}

DELETE /api/v1/trajectories/{id} - Delete trajectory

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Trajectory ID

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

PATCH /api/v1/trajectories/{id} - Update trajectory

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Trajectory ID

Request Body schema: application/json
required
description
string or null

New description (if changing)

metadata
object or null

New metadata (if changing)

name
string or null

New name (if changing)

null or TrajectoryStatus (string)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "metadata": { },
  • "name": "string",
  • "status": { }
}

Response samples

Content type
application/json
{
  • "_links": { },
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "metadata": { },
  • "name": "string",
  • "outcome": { },
  • "parent_trajectory_id": "d47865db-aef0-4c15-933a-0cc936082ee8",
  • "root_trajectory_id": "0f25abaa-7f0a-46dc-9cd9-abd889afef7f",
  • "status": "active",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "updated_at": "2019-08-24T14:15:22Z"
}

GET /api/v1/trajectories/{id}/children - List child trajectories

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Trajectory ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

GET /api/v1/trajectories/{id}/scopes - List scopes for trajectory

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Trajectory ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Scopes

Context window partitioning with checkpointing

POST /api/v1/scopes - Create a new scope

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
metadata
object or null

Additional metadata

name
required
string

Name of the scope

parent_scope_id
string or null <uuid>

Parent scope (for nested scopes)

purpose
string or null

Purpose/description

token_budget
required
integer <int32>

Token budget for this scope

trajectory_id
required
string <uuid>

Trajectory this scope belongs to

Responses

Request samples

Content type
application/json
{
  • "metadata": { },
  • "name": "string",
  • "parent_scope_id": "45ef4eca-ba00-47a4-995f-062c85c59e19",
  • "purpose": "string",
  • "token_budget": 0,
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

Response samples

Content type
application/json
{
  • "_links": { },
  • "checkpoint": { },
  • "closed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "is_active": true,
  • "metadata": { },
  • "name": "string",
  • "parent_scope_id": "45ef4eca-ba00-47a4-995f-062c85c59e19",
  • "purpose": "string",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "token_budget": 0,
  • "tokens_used": 0,
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

GET /api/v1/scopes/{id} - Get scope by ID

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Scope ID

Responses

Response samples

Content type
application/json
{
  • "_links": { },
  • "checkpoint": { },
  • "closed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "is_active": true,
  • "metadata": { },
  • "name": "string",
  • "parent_scope_id": "45ef4eca-ba00-47a4-995f-062c85c59e19",
  • "purpose": "string",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "token_budget": 0,
  • "tokens_used": 0,
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

PATCH /api/v1/scopes/{id} - Update scope

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Scope ID

Request Body schema: application/json
required
metadata
object or null

New metadata (if changing)

name
string or null

New name (if changing)

purpose
string or null

New purpose (if changing)

token_budget
integer or null <int32>

New token budget (if changing)

Responses

Request samples

Content type
application/json
{
  • "metadata": { },
  • "name": "string",
  • "purpose": "string",
  • "token_budget": 0
}

Response samples

Content type
application/json
{
  • "_links": { },
  • "checkpoint": { },
  • "closed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "is_active": true,
  • "metadata": { },
  • "name": "string",
  • "parent_scope_id": "45ef4eca-ba00-47a4-995f-062c85c59e19",
  • "purpose": "string",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "token_budget": 0,
  • "tokens_used": 0,
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

GET /api/v1/scopes/{id}/artifacts - List artifacts for scope

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Scope ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

POST /api/v1/scopes/{id}/checkpoint - Create checkpoint

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Scope ID

Request Body schema: application/json
required
context_state
required
string <byte>

Serialized context state

recoverable
required
boolean

Whether this checkpoint is recoverable

Responses

Request samples

Content type
application/json
{
  • "context_state": "string",
  • "recoverable": true
}

Response samples

Content type
application/json
{
  • "context_state": "string",
  • "recoverable": true
}

POST /api/v1/scopes/{id}/close - Close scope

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Scope ID

Responses

Response samples

Content type
application/json
{
  • "_links": { },
  • "checkpoint": { },
  • "closed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "is_active": true,
  • "metadata": { },
  • "name": "string",
  • "parent_scope_id": "45ef4eca-ba00-47a4-995f-062c85c59e19",
  • "purpose": "string",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "token_budget": 0,
  • "tokens_used": 0,
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

GET /api/v1/scopes/{id}/turns - List turns for scope

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Scope ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Artifacts

Typed outputs preserved across scopes

GET /api/v1/artifacts - List artifacts with filters

Authorizations:
api_keybearer_auth
query Parameters
artifact_type
string

Filter by artifact type

trajectory_id
string

Filter by trajectory ID

scope_id
string

Filter by scope ID

created_after
string

Filter by creation date (after)

created_before
string

Filter by creation date (before)

limit
integer <int32>

Maximum number of results

offset
integer <int32>

Offset for pagination

Responses

Response samples

Content type
application/json
{
  • "artifacts": [
    ],
  • "total": 0
}

POST /api/v1/artifacts - Create a new artifact

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
artifact_type
required
string (ArtifactType)
Enum: "error_log" "code_patch" "design_decision" "user_preference" "fact" "constraint" "tool_result" "intermediate_output" "custom" "code" "document" "data" "model" "config" "log" "summary" "decision" "plan" "audio" "image" "video" "transcript" "screenshot"

Type of artifact

confidence
number or null <float>

Confidence score (0.0-1.0)

content
required
string

Content of the artifact

extraction_method
required
string (ExtractionMethod)
Enum: "explicit" "inferred" "user_provided" "llm_extraction" "tool_extraction" "memory_recall" "external_api" "unknown"

Extraction method used

metadata
object or null

Additional metadata

name
required
string

Name of the artifact

scope_id
required
string <uuid>

Scope this artifact was created in

source_turn
required
integer <int32>

Source turn number

trajectory_id
required
string <uuid>

Trajectory this artifact belongs to

required
string or string or string or object or string or string or string or string or string or object (TTL)

Responses

Request samples

Content type
application/json
{
  • "artifact_type": "error_log",
  • "confidence": 0,
  • "content": "string",
  • "extraction_method": "explicit",
  • "metadata": { },
  • "name": "string",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "source_turn": 0,
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "ttl": "persistent"
}

Response samples

Content type
application/json
{
  • "_links": { },
  • "access_count": 0,
  • "accessed_at": "2019-08-24T14:15:22Z",
  • "artifact_id": "b7bd6bbb-c7f1-4314-8742-2aeeeece9d12",
  • "artifact_type": "error_log",
  • "content": "string",
  • "content_hash": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "embedding": { },
  • "metadata": { },
  • "name": "string",
  • "provenance": {
    },
  • "receipt_hash": "string",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "superseded_by": "a99fa58d-1b9b-4688-ad5f-382f6b17ef46",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "ttl": "persistent",
  • "updated_at": "2019-08-24T14:15:22Z"
}

POST /api/v1/artifacts/search - Search artifacts by similarity

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
entity_types
required
Array of strings (EntityType)
Items Enum: "trajectory" "scope" "artifact" "note" "turn" "tenant" "agent_working_set" "link" "belief" "goal" "plan" "lock" "message" "agent" "delegation" "handoff" "config" "conflict" "edge" "evolution_snapshot" "summarization_policy" "summarization_request" "tool_execution" "event"

Entity types to search

required
Array of objects (FilterExpr)

Additional filters

limit
integer or null <int64>

Maximum number of results

query
required
string

Search query text

use_vector_search
boolean or null

Enable vector-based semantic search (default: false for backwards compat) When true, results are ranked by embedding similarity instead of keyword matching

Responses

Request samples

Content type
application/json
{
  • "entity_types": [
    ],
  • "filters": [
    ],
  • "limit": 0,
  • "query": "string",
  • "use_vector_search": true
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 0
}

GET /api/v1/artifacts/{id} - Get artifact by ID

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Artifact ID

Responses

Response samples

Content type
application/json
{
  • "_links": { },
  • "access_count": 0,
  • "accessed_at": "2019-08-24T14:15:22Z",
  • "artifact_id": "b7bd6bbb-c7f1-4314-8742-2aeeeece9d12",
  • "artifact_type": "error_log",
  • "content": "string",
  • "content_hash": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "embedding": { },
  • "metadata": { },
  • "name": "string",
  • "provenance": {
    },
  • "receipt_hash": "string",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "superseded_by": "a99fa58d-1b9b-4688-ad5f-382f6b17ef46",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "ttl": "persistent",
  • "updated_at": "2019-08-24T14:15:22Z"
}

DELETE /api/v1/artifacts/{id} - Delete artifact

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Artifact ID

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

PATCH /api/v1/artifacts/{id} - Update artifact

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Artifact ID

Request Body schema: application/json
required
null or ArtifactType (string)
content
string or null

New content (if changing)

metadata
object or null

New metadata (if changing)

name
string or null

New name (if changing)

null or (TTL (TTL (string) or TTL (string) or TTL (string) or TTL (object) or TTL (string) or TTL (string) or TTL (string) or TTL (string) or TTL (string) or TTL (object)))

Responses

Request samples

Content type
application/json
{
  • "artifact_type": { },
  • "content": "string",
  • "metadata": { },
  • "name": "string",
  • "ttl": { }
}

Response samples

Content type
application/json
{
  • "_links": { },
  • "access_count": 0,
  • "accessed_at": "2019-08-24T14:15:22Z",
  • "artifact_id": "b7bd6bbb-c7f1-4314-8742-2aeeeece9d12",
  • "artifact_type": "error_log",
  • "content": "string",
  • "content_hash": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "embedding": { },
  • "metadata": { },
  • "name": "string",
  • "provenance": {
    },
  • "receipt_hash": "string",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "superseded_by": "a99fa58d-1b9b-4688-ad5f-382f6b17ef46",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "ttl": "persistent",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Notes

Long-term cross-trajectory knowledge

GET /api/v1/notes - List notes with filters

Authorizations:
api_keybearer_auth
query Parameters
note_type
string

Filter by note type

source_trajectory_id
string

Filter by source trajectory ID

created_after
string

Filter by creation date (after)

created_before
string

Filter by creation date (before)

limit
integer <int32>

Maximum number of results

offset
integer <int32>

Offset for pagination

Responses

Response samples

Content type
application/json
{
  • "notes": [
    ],
  • "total": 0
}

POST /api/v1/notes - Create a new note

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
content
required
string

Content of the note

metadata
object or null

Additional metadata

note_type
required
string (NoteType)
Enum: "convention" "strategy" "gotcha" "fact" "preference" "relationship" "procedure" "meta" "insight" "correction" "summary"

Type of note

source_artifact_ids
required
Array of strings

Source artifacts

source_note_ids
Array of strings

Source notes (for derived notes and abstraction chains)

source_trajectory_ids
required
Array of strings

Source trajectories

title
required
string

Title of the note

required
string or string or string or object or string or string or string or string or string or object (TTL)

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "metadata": { },
  • "note_type": "convention",
  • "source_artifact_ids": [
    ],
  • "source_note_ids": [
    ],
  • "source_trajectory_ids": [
    ],
  • "title": "string",
  • "ttl": "persistent"
}

Response samples

Content type
application/json
{
  • "_links": { },
  • "abstraction_level": "raw",
  • "access_count": 0,
  • "accessed_at": "2019-08-24T14:15:22Z",
  • "content": "string",
  • "content_hash": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "embedding": { },
  • "metadata": { },
  • "note_id": "f37a7c27-f466-4182-88ae-001e80802cdc",
  • "note_type": "convention",
  • "receipt_hash": "string",
  • "source_artifact_ids": [
    ],
  • "source_note_ids": [
    ],
  • "source_trajectory_ids": [
    ],
  • "superseded_by": "a99fa58d-1b9b-4688-ad5f-382f6b17ef46",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "title": "string",
  • "ttl": "persistent",
  • "updated_at": "2019-08-24T14:15:22Z"
}

POST /api/v1/notes/search - Search notes by similarity

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
entity_types
required
Array of strings (EntityType)
Items Enum: "trajectory" "scope" "artifact" "note" "turn" "tenant" "agent_working_set" "link" "belief" "goal" "plan" "lock" "message" "agent" "delegation" "handoff" "config" "conflict" "edge" "evolution_snapshot" "summarization_policy" "summarization_request" "tool_execution" "event"

Entity types to search

required
Array of objects (FilterExpr)

Additional filters

limit
integer or null <int64>

Maximum number of results

query
required
string

Search query text

use_vector_search
boolean or null

Enable vector-based semantic search (default: false for backwards compat) When true, results are ranked by embedding similarity instead of keyword matching

Responses

Request samples

Content type
application/json
{
  • "entity_types": [
    ],
  • "filters": [
    ],
  • "limit": 0,
  • "query": "string",
  • "use_vector_search": true
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 0
}

GET /api/v1/notes/{id} - Get note by ID

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Note ID

Responses

Response samples

Content type
application/json
{
  • "_links": { },
  • "abstraction_level": "raw",
  • "access_count": 0,
  • "accessed_at": "2019-08-24T14:15:22Z",
  • "content": "string",
  • "content_hash": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "embedding": { },
  • "metadata": { },
  • "note_id": "f37a7c27-f466-4182-88ae-001e80802cdc",
  • "note_type": "convention",
  • "receipt_hash": "string",
  • "source_artifact_ids": [
    ],
  • "source_note_ids": [
    ],
  • "source_trajectory_ids": [
    ],
  • "superseded_by": "a99fa58d-1b9b-4688-ad5f-382f6b17ef46",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "title": "string",
  • "ttl": "persistent",
  • "updated_at": "2019-08-24T14:15:22Z"
}

DELETE /api/v1/notes/{id} - Delete note

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Note ID

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

PATCH /api/v1/notes/{id} - Update note

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Note ID

Request Body schema: application/json
required
content
string or null

New content (if changing)

metadata
object or null

New metadata (if changing)

null or NoteType (string)
title
string or null

New title (if changing)

null or (TTL (TTL (string) or TTL (string) or TTL (string) or TTL (object) or TTL (string) or TTL (string) or TTL (string) or TTL (string) or TTL (string) or TTL (object)))

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "metadata": { },
  • "note_type": { },
  • "title": "string",
  • "ttl": { }
}

Response samples

Content type
application/json
{
  • "_links": { },
  • "abstraction_level": "raw",
  • "access_count": 0,
  • "accessed_at": "2019-08-24T14:15:22Z",
  • "content": "string",
  • "content_hash": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "embedding": { },
  • "metadata": { },
  • "note_id": "f37a7c27-f466-4182-88ae-001e80802cdc",
  • "note_type": "convention",
  • "receipt_hash": "string",
  • "source_artifact_ids": [
    ],
  • "source_note_ids": [
    ],
  • "source_trajectory_ids": [
    ],
  • "superseded_by": "a99fa58d-1b9b-4688-ad5f-382f6b17ef46",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "title": "string",
  • "ttl": "persistent",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Turns

Ephemeral conversation buffer entries

POST /api/v1/turns - Create a new turn

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
content
required
string

Content of the turn

metadata
object or null

Additional metadata

role
required
string (TurnRole)
Enum: "user" "assistant" "system" "tool"

Role of the turn

scope_id
required
string <uuid>

Scope this turn belongs to

sequence
integer <int32>

Sequence number within the scope (auto-assigned as 0 if omitted)

token_count
integer <int32>

Token count (defaults to 0 if omitted)

tool_calls
object or null

Tool calls (if any)

tool_results
object or null

Tool results (if any)

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "metadata": { },
  • "role": "user",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "sequence": 0,
  • "token_count": 0,
  • "tool_calls": { },
  • "tool_results": { }
}

Response samples

Content type
application/json
{
  • "content": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "metadata": { },
  • "role": "user",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "sequence": 0,
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "token_count": 0,
  • "tool_calls": { },
  • "tool_results": { },
  • "turn_id": "2df5d97e-1e68-4315-ace5-61a464d94d93"
}

GET /api/v1/turns/{id} - Get turn by ID

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Turn ID

Responses

Response samples

Content type
application/json
{
  • "content": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "metadata": { },
  • "role": "user",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "sequence": 0,
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "token_count": 0,
  • "tool_calls": { },
  • "tool_results": { },
  • "turn_id": "2df5d97e-1e68-4315-ace5-61a464d94d93"
}

Agents

Multi-agent registration and management

GET /api/v1/agents - List agents with filters

Authorizations:
api_keybearer_auth
query Parameters
agent_type
string

Filter by agent type

status
string

Filter by status

trajectory_id
string

Filter by current trajectory

active_only
boolean

Only return active agents

Responses

Response samples

Content type
application/json
{
  • "agents": [
    ],
  • "total": 0
}

POST /api/v1/agents - Register a new agent

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
required
string or string or string or string or string or object (AgentType)
can_delegate_to
required
Array of strings

Agent types this agent can delegate to

capabilities
required
Array of strings

Capabilities this agent has

required
object (MemoryAccessRequest)

Memory access permissions

owner_principal_id
string or null <uuid>

Optional explicit owner principal. If omitted, request principal is used.

reports_to
string or null <uuid>

Supervisor agent (if any)

Responses

Request samples

Content type
application/json
{
  • "agent_type": "Tester",
  • "can_delegate_to": [
    ],
  • "capabilities": [
    ],
  • "memory_access": {
    },
  • "owner_principal_id": "fe39bf7b-6b2d-42fc-be7f-80505e2d7f4f",
  • "reports_to": "788f594d-4490-438b-9a88-e4150fb7d6c0"
}

Response samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "agent_type": "Tester",
  • "can_delegate_to": [
    ],
  • "capabilities": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "current_scope_id": "378c4d70-6e96-4fbe-914c-41be9d86b91a",
  • "current_trajectory_id": "c1f5eb9b-8706-4841-8412-80dfc13e0a58",
  • "last_heartbeat_at": "2019-08-24T14:15:22Z",
  • "memory_access": {
    },
  • "owner_principal_id": "fe39bf7b-6b2d-42fc-be7f-80505e2d7f4f",
  • "reports_to": "788f594d-4490-438b-9a88-e4150fb7d6c0",
  • "status": "idle",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

GET /api/v1/agents/{id} - Get agent by ID

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Agent ID

Responses

Response samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "agent_type": "Tester",
  • "can_delegate_to": [
    ],
  • "capabilities": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "current_scope_id": "378c4d70-6e96-4fbe-914c-41be9d86b91a",
  • "current_trajectory_id": "c1f5eb9b-8706-4841-8412-80dfc13e0a58",
  • "last_heartbeat_at": "2019-08-24T14:15:22Z",
  • "memory_access": {
    },
  • "owner_principal_id": "fe39bf7b-6b2d-42fc-be7f-80505e2d7f4f",
  • "reports_to": "788f594d-4490-438b-9a88-e4150fb7d6c0",
  • "status": "idle",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

DELETE /api/v1/agents/{id} - Unregister agent

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Agent ID

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

PATCH /api/v1/agents/{id} - Update agent

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Agent ID

Request Body schema: application/json
required
capabilities
Array of strings or null

New capabilities (if changing)

current_scope_id
string or null <uuid>

New current scope (if changing)

current_trajectory_id
string or null <uuid>

New current trajectory (if changing)

null or MemoryAccessRequest (object)
null or AgentStatus (string)

Responses

Request samples

Content type
application/json
{
  • "capabilities": [
    ],
  • "current_scope_id": "378c4d70-6e96-4fbe-914c-41be9d86b91a",
  • "current_trajectory_id": "c1f5eb9b-8706-4841-8412-80dfc13e0a58",
  • "memory_access": { },
  • "status": { }
}

Response samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "agent_type": "Tester",
  • "can_delegate_to": [
    ],
  • "capabilities": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "current_scope_id": "378c4d70-6e96-4fbe-914c-41be9d86b91a",
  • "current_trajectory_id": "c1f5eb9b-8706-4841-8412-80dfc13e0a58",
  • "last_heartbeat_at": "2019-08-24T14:15:22Z",
  • "memory_access": {
    },
  • "owner_principal_id": "fe39bf7b-6b2d-42fc-be7f-80505e2d7f4f",
  • "reports_to": "788f594d-4490-438b-9a88-e4150fb7d6c0",
  • "status": "idle",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

POST /api/v1/agents/{id}/heartbeat - Send agent heartbeat

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Agent ID

Responses

Response samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "agent_type": "Tester",
  • "can_delegate_to": [
    ],
  • "capabilities": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "current_scope_id": "378c4d70-6e96-4fbe-914c-41be9d86b91a",
  • "current_trajectory_id": "c1f5eb9b-8706-4841-8412-80dfc13e0a58",
  • "last_heartbeat_at": "2019-08-24T14:15:22Z",
  • "memory_access": {
    },
  • "owner_principal_id": "fe39bf7b-6b2d-42fc-be7f-80505e2d7f4f",
  • "reports_to": "788f594d-4490-438b-9a88-e4150fb7d6c0",
  • "status": "idle",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

Locks

Distributed locking for resource coordination

GET /api/v1/locks - List all active locks

Authorizations:
api_keybearer_auth

Responses

Response samples

Content type
application/json
{
  • "locks": [
    ],
  • "total": 0
}

POST /api/v1/locks/acquire - Acquire a distributed lock

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
holder_agent_id
required
string <uuid>

Agent requesting the lock

mode
required
string

Lock mode (Exclusive or Shared)

resource_id
required
string <uuid>

ID of the resource to lock

resource_type
required
string (ResourceType)
Enum: "trajectory" "scope" "artifact" "note" "agent"

Type of resource to lock

timeout_ms
required
integer <int64>

Lock timeout in milliseconds

Responses

Request samples

Content type
application/json
{
  • "holder_agent_id": "7d3e49bb-e0f5-470b-bcaa-ee120b9f574d",
  • "mode": "string",
  • "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
  • "resource_type": "trajectory",
  • "timeout_ms": 0
}

Response samples

Content type
application/json
{
  • "acquired_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "holder_agent_id": "7d3e49bb-e0f5-470b-bcaa-ee120b9f574d",
  • "lock_id": "c7590aa3-358c-4ba6-a3b5-87d5f487fd16",
  • "mode": "string",
  • "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
  • "resource_type": "trajectory",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

GET /api/v1/locks/{id} - Get lock by ID

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Lock ID

Responses

Response samples

Content type
application/json
{
  • "acquired_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "holder_agent_id": "7d3e49bb-e0f5-470b-bcaa-ee120b9f574d",
  • "lock_id": "c7590aa3-358c-4ba6-a3b5-87d5f487fd16",
  • "mode": "string",
  • "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
  • "resource_type": "trajectory",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

POST /api/v1/locks/{id}/extend - Extend a lock's expiration time

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Lock ID

Request Body schema: application/json
required
additional_ms
required
integer <int64>

Additional time in milliseconds

Responses

Request samples

Content type
application/json
{
  • "additional_ms": 0
}

Response samples

Content type
application/json
{
  • "acquired_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "holder_agent_id": "7d3e49bb-e0f5-470b-bcaa-ee120b9f574d",
  • "lock_id": "c7590aa3-358c-4ba6-a3b5-87d5f487fd16",
  • "mode": "string",
  • "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
  • "resource_type": "trajectory",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

POST /api/v1/locks/{id}/release - Release a distributed lock

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Lock ID

Request Body schema: application/json
required
releasing_agent_id
required
string <uuid>

Agent releasing the lock (must be the holder)

Responses

Request samples

Content type
application/json
{
  • "releasing_agent_id": "6364ddb7-59d4-4a83-bd2a-f7236f9c2286"
}

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

Messages

Inter-agent communication

GET /api/v1/messages - List messages with filters

Authorizations:
api_keybearer_auth
query Parameters
message_type
string

Filter by message type

from_agent_id
string

Filter by sender agent

to_agent_id
string

Filter by recipient agent

to_agent_type
string

Filter by recipient agent type

trajectory_id
string

Filter by trajectory

priority
string

Filter by priority

undelivered_only
boolean

Only return undelivered messages

unacknowledged_only
boolean

Only return unacknowledged messages

limit
integer <int32>

Maximum number of results

offset
integer <int32>

Offset for pagination

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "total": 0
}

POST /api/v1/messages - Send a message

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
artifact_ids
required
Array of strings

Related artifacts (if any)

expires_at
string or null <date-time>

When the message expires (optional)

from_agent_id
required
string <uuid>

Agent sending the message

message_type
required
string (MessageType)
Enum: "task_delegation" "task_result" "context_request" "context_share" "coordination_signal" "handoff" "interrupt" "heartbeat"

Type of message

payload
required
string

Message payload (JSON serialized)

priority
required
string (MessagePriority)
Enum: "low" "normal" "high" "critical"

Message priority

scope_id
string or null <uuid>

Related scope (if any)

null or (AgentTarget (AgentTarget (object) or AgentTarget (object)))
trajectory_id
string or null <uuid>

Related trajectory (if any)

Responses

Request samples

Content type
application/json
{
  • "artifact_ids": [
    ],
  • "expires_at": "2019-08-24T14:15:22Z",
  • "from_agent_id": "5263c7c6-e676-46d8-a6d1-3555c9c1605e",
  • "message_type": "task_delegation",
  • "payload": "string",
  • "priority": "low",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "to": { },
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

Response samples

Content type
application/json
{
  • "acknowledged_at": "2019-08-24T14:15:22Z",
  • "artifact_ids": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "delivered_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "message_id": "d7d9d9fd-478f-40e6-b651-49b7f19878a2",
  • "message_type": "task_delegation",
  • "payload": "string",
  • "priority": "low",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "sender_id": "3194e023-c19f-4a42-9172-9e18d68e3a3a",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "to": { },
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

GET /api/v1/messages/{id} - Get message by ID

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Message ID

Responses

Response samples

Content type
application/json
{
  • "acknowledged_at": "2019-08-24T14:15:22Z",
  • "artifact_ids": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "delivered_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "message_id": "d7d9d9fd-478f-40e6-b651-49b7f19878a2",
  • "message_type": "task_delegation",
  • "payload": "string",
  • "priority": "low",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "sender_id": "3194e023-c19f-4a42-9172-9e18d68e3a3a",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "to": { },
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

POST /api/v1/messages/{id}/acknowledge - Acknowledge a message

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Message ID

Request Body schema: application/json
required
agent_id
required
string <uuid>

The agent performing the action (must be the message recipient)

Responses

Request samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978"
}

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

Delegations

Task delegation between agents

POST /api/v1/delegations - Create a task delegation

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
context
object or null

Additional context

expected_completion
string or null <date-time>

Expected completion time

from_agent_id
required
string <uuid>

Agent delegating the task

scope_id
required
string <uuid>

Scope for the delegated task

task_description
required
string

Task description

to_agent_id
required
string <uuid>

Agent receiving the delegation

trajectory_id
required
string <uuid>

Trajectory for the delegated task

Responses

Request samples

Content type
application/json
{
  • "context": { },
  • "expected_completion": "2019-08-24T14:15:22Z",
  • "from_agent_id": "5263c7c6-e676-46d8-a6d1-3555c9c1605e",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "task_description": "string",
  • "to_agent_id": "59132b1d-373f-4e40-ba51-efb09b82ca7a",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

Response samples

Content type
application/json
{
  • "accepted_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "context": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "delegatee_id": "4cb98d17-4291-4316-b7cc-d10cdf9c4d72",
  • "delegation_id": "4cff8b0a-bdd8-4ae9-8b8e-6f3c0f89b0a7",
  • "delegator_id": "a216129c-840c-4df6-a346-870cfb194797",
  • "expected_completion": "2019-08-24T14:15:22Z",
  • "result": { },
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "status": "pending",
  • "task_description": "string",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

GET /api/v1/delegations/{id} - Get delegation by ID

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Delegation ID

Responses

Response samples

Content type
application/json
{
  • "accepted_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "context": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "delegatee_id": "4cb98d17-4291-4316-b7cc-d10cdf9c4d72",
  • "delegation_id": "4cff8b0a-bdd8-4ae9-8b8e-6f3c0f89b0a7",
  • "delegator_id": "a216129c-840c-4df6-a346-870cfb194797",
  • "expected_completion": "2019-08-24T14:15:22Z",
  • "result": { },
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "status": "pending",
  • "task_description": "string",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

POST /api/v1/delegations/{id}/accept - Accept a delegation

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Delegation ID

Request Body schema: application/json
required
accepting_agent_id
required
string <uuid>

Agent accepting the delegation

Responses

Request samples

Content type
application/json
{
  • "accepting_agent_id": "d9e821c5-f88a-4dba-8a51-7c82e765fb7a"
}

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

POST /api/v1/delegations/{id}/complete - Complete a delegation

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Delegation ID

Request Body schema: application/json
required
completing_agent_id
required
string <uuid>

Agent completing the delegation (must be the delegatee)

required
object (DelegationResultResponse)

Result of the delegation

Responses

Request samples

Content type
application/json
{
  • "completing_agent_id": "a9798242-682a-4858-aa27-afedd7b81e30",
  • "result": {
    }
}

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

POST /api/v1/delegations/{id}/reject - Reject a delegation

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Delegation ID

Request Body schema: application/json
required
reason
required
string

Reason for rejection

rejecting_agent_id
required
string <uuid>

Agent rejecting the delegation

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "rejecting_agent_id": "9c6e9ffc-c7e7-4292-8a96-1d6ab9126e18"
}

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

Handoffs

Context handoff between agents

POST /api/v1/handoffs - Create an agent handoff

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
context_snapshot
required
string <byte>

Context to transfer

from_agent_id
required
string <uuid>

Agent initiating the handoff

reason
required
string

Reason for handoff

scope_id
required
string <uuid>

Current scope

to_agent_id
required
string <uuid>

Agent receiving the handoff

trajectory_id
required
string <uuid>

Trajectory being handed off

Responses

Request samples

Content type
application/json
{
  • "context_snapshot": "string",
  • "from_agent_id": "5263c7c6-e676-46d8-a6d1-3555c9c1605e",
  • "reason": "string",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "to_agent_id": "59132b1d-373f-4e40-ba51-efb09b82ca7a",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

Response samples

Content type
application/json
{
  • "accepted_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "context_snapshot": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "from_agent_id": "5263c7c6-e676-46d8-a6d1-3555c9c1605e",
  • "handoff_id": "141e6d39-e6f2-4d75-8027-a089e03fcad6",
  • "reason": "string",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "status": "initiated",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "to_agent_id": "59132b1d-373f-4e40-ba51-efb09b82ca7a",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

GET /api/v1/handoffs/{id} - Get handoff by ID

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Handoff ID

Responses

Response samples

Content type
application/json
{
  • "accepted_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "context_snapshot": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "from_agent_id": "5263c7c6-e676-46d8-a6d1-3555c9c1605e",
  • "handoff_id": "141e6d39-e6f2-4d75-8027-a089e03fcad6",
  • "reason": "string",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "status": "initiated",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "to_agent_id": "59132b1d-373f-4e40-ba51-efb09b82ca7a",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

POST /api/v1/handoffs/{id}/accept - Accept a handoff

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Handoff ID

Request Body schema: application/json
required
accepting_agent_id
required
string <uuid>

Agent accepting the handoff

Responses

Request samples

Content type
application/json
{
  • "accepting_agent_id": "d9e821c5-f88a-4dba-8a51-7c82e765fb7a"
}

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

POST /api/v1/handoffs/{id}/complete - Complete a handoff

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Handoff ID

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

Search

Global search across entities

POST /api/v1/search - Global search across entities

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
entity_types
required
Array of strings (EntityType)
Items Enum: "trajectory" "scope" "artifact" "note" "turn" "tenant" "agent_working_set" "link" "belief" "goal" "plan" "lock" "message" "agent" "delegation" "handoff" "config" "conflict" "edge" "evolution_snapshot" "summarization_policy" "summarization_request" "tool_execution" "event"

Entity types to search

required
Array of objects (FilterExpr)

Additional filters

limit
integer or null <int64>

Maximum number of results

query
required
string

Search query text

use_vector_search
boolean or null

Enable vector-based semantic search (default: false for backwards compat) When true, results are ranked by embedding similarity instead of keyword matching

Responses

Request samples

Content type
application/json
{
  • "entity_types": [
    ],
  • "filters": [
    ],
  • "limit": 0,
  • "query": "string",
  • "use_vector_search": true
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 0
}

Pack Config

Pack configuration validation and parsing

POST /api/v1/pack-config/compose - Compose pack (TOML + Markdown) to AST + compiled config

Authorizations:
api_keybearer_auth
Request Body schema: multipart/form-data
required
cstate_toml
required
string

cstate.toml contents

markdown
required
Array of strings

Markdown prompt files (each part content)

Responses

Response samples

Content type
application/json
{
  • "ast": { },
  • "compiled": { },
  • "errors": [
    ],
  • "pack_source": "string",
  • "success": true
}

Parses pack Markdown source and returns a validation response containing the AST or parse errors.

On success the response's ast field contains the parsed Abstract Syntax Tree (AST) serialized as JSON. On failure the response includes one or more ParseErrorResponse entries with error messages (line and column are set to 0 for parse errors produced by the internal pack parser).

Examples

// Prefer using the HTTP endpoint in integration tests; for local parsing the helper can be used:
let source = "# My Pack\n...";
let ast = cellstate_api::utils::parse_markdown_source(source).expect("should parse");
let ast_json = serde_json::to_value(&ast).unwrap();
assert!(ast_json.is_object());
Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
source
required
string

pack source code

Responses

Request samples

Content type
application/json
{
  • "source": "string"
}

Response samples

Content type
application/json
{
  • "ast": { },
  • "errors": [
    ],
  • "valid": true
}

Validate a pack Markdown source and return either its parsed AST or parse diagnostics.

Validates that the provided request source is not empty; if empty, the request is rejected with a missing-field error. On successful parsing the response contains valid: true and ast set to the serialized AST. On parse failure the response contains valid: false and a single ParseErrorResponse with line: 0, column: 0, and message set to the parser error string.

Examples

use axum::Json;
use cellstate_api::ValidatePackRequest;

// Construct a request with pack source and send it to the handler.
let req = ValidatePackRequest { source: "# Example Pack".into() };
// Calling the handler requires a `State<DbClient>`; in integration tests provide a test DbClient.
// let response = tokio::runtime::Runtime::new().unwrap().block_on(validate_pack(state, Json(req)));
Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
source
required
string

pack source code

Responses

Request samples

Content type
application/json
{
  • "source": "string"
}

Response samples

Content type
application/json
{
  • "ast": { },
  • "errors": [
    ],
  • "valid": true
}

Config

System configuration

GET /api/v1/config - Get current configuration

Authorizations:
api_keybearer_auth

Responses

Response samples

Content type
application/json
{
  • "config": { },
  • "errors": [
    ],
  • "valid": true
}

PATCH /api/v1/config - Update configuration

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
config
required
object

Configuration as JSON

Responses

Request samples

Content type
application/json
{
  • "config": { }
}

Response samples

Content type
application/json
{
  • "config": { },
  • "errors": [
    ],
  • "valid": true
}

POST /api/v1/config/validate - Validate configuration

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
config
required
object

Configuration as JSON to validate

Responses

Request samples

Content type
application/json
{
  • "config": { }
}

Response samples

Content type
application/json
{
  • "config": { },
  • "errors": [
    ],
  • "valid": true
}

Deployments

Pack deployment lifecycle and rollout management

GET /api/v1/deployments — List deployments for a pack.

Authorizations:
api_keybearer_auth
query Parameters
pack_name
required
string

Pack name

Responses

Response samples

Content type
application/json
{
  • "deployments": [
    ],
  • "total": 0
}

POST /api/v1/deployments — Create a new deployment version.

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
error_threshold
number <double>
null or DeploymentLaunchConfig (object)
pack_name
required
string

Responses

Request samples

Content type
application/json
{
  • "error_threshold": 0.1,
  • "launch_config": { },
  • "pack_name": "string"
}

Response samples

Content type
application/json
{
  • "deployment": {
    }
}

POST /api/v1/deployments/rollback — Rollback a deployment for a pack.

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
pack_name
required
string

Responses

Request samples

Content type
application/json
{
  • "pack_name": "string"
}

Response samples

Content type
application/json
{
  • "deployment": {
    }
}

GET /api/v1/deployments/:id — Get a single deployment.

Authorizations:
api_keybearer_auth
path Parameters
id
required
string

Deployment ID

Responses

Response samples

Content type
application/json
{
  • "deployment": {
    }
}

POST /api/v1/deployments/:id/activate — Activate a deployment with rollout %.

Authorizations:
api_keybearer_auth
path Parameters
id
required
string

Deployment ID

Request Body schema: application/json
required
rollout_percentage
required
integer <int32> >= 0

Responses

Request samples

Content type
application/json
{
  • "rollout_percentage": 0
}

Response samples

Content type
application/json
{
  • "deployment": {
    }
}

POST /api/v1/deployments/:id/rollout — Increase rollout percentage.

Authorizations:
api_keybearer_auth
path Parameters
id
required
string

Deployment ID

Request Body schema: application/json
required
rollout_percentage
required
integer <int32> >= 0

Responses

Request samples

Content type
application/json
{
  • "rollout_percentage": 0
}

Response samples

Content type
application/json
{
  • "deployment": {
    }
}

API Keys

API key management for programmatic access

GET /api/v1/api-keys - List API keys for the current user

Authorizations:
bearer_auth
query Parameters
is_active
boolean

Filter by active status

name
string

Filter by name (substring match)

limit
integer <int32>

Maximum number of results

offset
integer <int32>

Offset for pagination

Responses

Response samples

Content type
application/json
{
  • "api_keys": [
    ],
  • "total": 0
}

POST /api/v1/api-keys - Create an API key

Authorizations:
bearer_auth
Request Body schema: application/json
required
expires_at
string or null <date-time>
name
required
string
scopes
Array of strings or null

Responses

Request samples

Content type
application/json
{
  • "expires_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "api_key": {
    },
  • "key": "string"
}

GET /api/v1/api-keys/admin/tenants/{tenant_id} - Admin list API keys for a tenant

Authorizations:
bearer_auth
path Parameters
tenant_id
required
string <uuid>

Tenant ID

query Parameters
is_active
boolean

Filter by active status

name
string

Filter by name (substring match)

owner_user_id
string

Filter by owner user ID

limit
integer <int32>

Maximum number of results

offset
integer <int32>

Offset for pagination

Responses

Response samples

Content type
application/json
{
  • "api_keys": [
    ],
  • "total": 0
}

POST /api/v1/api-keys/admin/tenants/{tenant_id}/{id}/revoke - Admin revoke API key

Authorizations:
bearer_auth
path Parameters
tenant_id
required
string <uuid>

Tenant ID

id
required
string <uuid>

API key ID

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

POST /api/v1/api-keys/{id}/revoke - Revoke an API key

Authorizations:
bearer_auth
path Parameters
id
required
string <uuid>

API key ID

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

Users

Authenticated user profile and self-service credentials

GET /api/v1/users/me - Get current user's profile

Authorizations:
api_keybearer_auth

Responses

Response samples

Content type
application/json
{
  • "api_key": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "email": "string",
  • "first_name": "string",
  • "id": "string",
  • "last_name": "string",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

POST /api/v1/users/me/api-key - Regenerate API key

Authorizations:
bearer_auth

Responses

Response samples

Content type
application/json
{
  • "api_key": "string"
}

OAuth

OAuth provider token vault management

callback_oauth_provider

query Parameters
code
string

OAuth authorization code

state
string

OAuth state token

error
string

Provider-side OAuth error

error_description
string

Provider-side OAuth error description

Responses

Response samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "provider": "string",
  • "scopes": [
    ],
  • "stored_at": "2019-08-24T14:15:22Z",
  • "token_type": "string"
}

connect_oauth_provider

Authorizations:
bearer_auth
Request Body schema: application/json
required
agent_id
string or null <uuid>
allow_signup
boolean or null
provider
required
string
redirect_uri
string or null
scopes
Array of strings or null

Responses

Request samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "allow_signup": true,
  • "provider": "string",
  • "redirect_uri": "string",
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "authorization_url": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "pkce_method": "string",
  • "provider": "string",
  • "state": "string"
}

list_oauth_tokens

Authorizations:
bearer_auth
query Parameters
provider
string

Optional provider filter

agent_id
string <uuid>

Optional agent filter

Responses

Response samples

Content type
application/json
{
  • "tokens": [
    ],
  • "total": 0
}

upsert_oauth_token

Authorizations:
bearer_auth
Request Body schema: application/json
required
access_token
required
string
agent_id
string or null <uuid>
expires_at
string or null <date-time>
provider
required
string
refresh_token
string or null
scopes
Array of strings or null
token_type
string or null

Responses

Request samples

Content type
application/json
{
  • "access_token": "string",
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "provider": "string",
  • "refresh_token": "string",
  • "scopes": [
    ],
  • "token_type": "string"
}

Response samples

Content type
application/json
{
  • "token": {
    }
}

revoke_oauth_token

Authorizations:
bearer_auth
Request Body schema: application/json
required
agent_id
string or null <uuid>
provider
required
string

Responses

Request samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "provider": "string"
}

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

rotate_oauth_token_encryption_keys

Authorizations:
bearer_auth

Responses

Response samples

Content type
application/json
{
  • "rotated_entries": 0
}

Tenants

Multi-tenant management

GET /api/v1/tenants - List all tenants accessible to the current user

SECURITY: Returns only tenants where the caller has membership. If no membership rows are present (for example API-key only contexts), falls back to the authenticated current tenant.

Authorizations:
api_keybearer_auth

Responses

Response samples

Content type
application/json
{
  • "tenants": [
    ]
}

GET /api/v1/tenants/{id} - Get tenant by ID

SECURITY: Users can only access their own tenant. This prevents information disclosure about other tenants' existence and details.

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Tenant ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "domain": "string",
  • "name": "string",
  • "settings": { },
  • "status": "active",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "workos_organization_id": "string"
}

PATCH /api/v1/tenants/{id} - Update tenant settings

SECURITY: Users can only update their own tenant.

Authorizations:
api_keybearer_auth
path Parameters
id
required
string <uuid>

Tenant ID

Request Body schema: application/json
required
domain
string or null

Updated email domain

name
string or null

Updated tenant name

settings
object or null

Updated tenant settings

null or TenantStatus (string)

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "name": "string",
  • "settings": { },
  • "status": { }
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "domain": "string",
  • "name": "string",
  • "settings": { },
  • "status": "active",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "workos_organization_id": "string"
}

Benchmarks

Evolution snapshot benchmarking and retrieval

GET /api/v1/benchmarks — list benchmark snapshots for the current tenant.

Authorizations:
api_keybearer_auth

Responses

Response samples

Content type
application/json
{
  • "snapshots": [
    ],
  • "total": 0
}

POST /api/v1/benchmarks — submit a benchmark snapshot event.

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
config_source
required
string
metadata
object or null
null or EvolutionMetrics (object)
name
required
string
phase
required
string (EvolutionPhase)
Enum: "online" "frozen" "evolving"

Phase of pack config evolution cycle.

Responses

Request samples

Content type
application/json
{
  • "config_source": "string",
  • "metadata": { },
  • "metrics": { },
  • "name": "string",
  • "phase": "online"
}

Response samples

Content type
application/json
{
  • "config_hash": "string",
  • "config_source": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "metadata": { },
  • "metrics": { },
  • "name": "string",
  • "phase": "online",
  • "snapshot_id": "163831af-8c1b-4992-a9cf-88c6306604c0"
}

EventDag

Event DAG traversal and forensic inspection

GET /api/v1/event-dag/by-kind/:kind - Search events by kind

Authorizations:
api_keybearer_auth
path Parameters
kind
required
integer <int32> >= 0

Event kind code (u16, e.g. 0x1001 = 4097 for TRAJECTORY_CREATED)

query Parameters
min_depth
integer <int32> >= 0

Minimum depth (default: 0)

max_depth
integer <int32> >= 0

Maximum depth (default: 999)

limit
integer >= 0

Maximum number of events to return (default: 100)

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "events": [
    ]
}

GET /api/v1/event-dag/:id - Read a single event by ID

Authorizations:
api_keybearer_auth
path Parameters
id
required
string

Event ID (UUID)

Responses

Response samples

Content type
application/json
{
  • "event": {
    }
}

GET /api/v1/event-dag/:id/ancestors - Walk ancestor chain

Authorizations:
api_keybearer_auth
path Parameters
id
required
string

Event ID (UUID)

query Parameters
limit
integer >= 0

Maximum number of ancestors to return (default: 100)

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "events": [
    ]
}

GET /api/v1/event-dag/:id/descendants - Walk descendant chain

Authorizations:
api_keybearer_auth
path Parameters
id
required
string

Event ID (UUID)

query Parameters
limit
integer >= 0

Maximum number of descendants to return (default: 100)

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "events": [
    ]
}

GET /api/v1/event-dag/:id/siblings - Find sibling events (same parent)

Reads the event to determine its parent (via correlation_id and position), then walks descendants of the parent to find siblings at the same depth.

Authorizations:
api_keybearer_auth
path Parameters
id
required
string

Event ID (UUID)

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "events": [
    ]
}

Edges

POST /api/v1/edges - Create a new edge

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
edge_type
required
string (EdgeType)
Enum: "supports" "contradicts" "supersedes" "derived_from" "relates_to" "temporal" "causal" "synthesized_from" "grouped" "compared"

Type of edge

metadata
any

Optional metadata

required
Array of objects (EdgeParticipantRequest)

Edge participants (entities involved)

required
object (ProvenanceRequest)

Provenance information

trajectory_id
string or null <uuid>

Optional trajectory ID for context

weight
number or null <float>

Optional weight/strength of relationship [0.0, 1.0]

Responses

Request samples

Content type
application/json
{
  • "edge_type": "supports",
  • "metadata": null,
  • "participants": [
    ],
  • "provenance": {
    },
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "weight": 0
}

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "edge_id": "b311b798-212e-414c-ba53-c572923101d4",
  • "edge_type": "supports",
  • "metadata": { },
  • "participants": [
    ],
  • "provenance": {
    },
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "weight": 0
}

POST /api/v1/edges/batch - Create multiple edges

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
Array
edge_type
required
string (EdgeType)
Enum: "supports" "contradicts" "supersedes" "derived_from" "relates_to" "temporal" "causal" "synthesized_from" "grouped" "compared"

Type of edge

metadata
any

Optional metadata

required
Array of objects (EdgeParticipantRequest)

Edge participants (entities involved)

required
object (ProvenanceRequest)

Provenance information

trajectory_id
string or null <uuid>

Optional trajectory ID for context

weight
number or null <float>

Optional weight/strength of relationship [0.0, 1.0]

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "edges": [
    ]
}

GET /api/v1/edges/by-participant/{entity_id} - Get edges by participant entity

Authorizations:
api_keybearer_auth
path Parameters
entity_id
required
string

Entity ID to find edges for

Responses

Response samples

Content type
application/json
{
  • "edges": [
    ]
}

GET /api/v1/edges/traverse - SQL graph traversal over cellstate_link.

Authorizations:
api_keybearer_auth
query Parameters
start_id
required
string

Start entity ID

max_depth
integer <int32>

Maximum traversal depth

rel_types
Array of strings

Optional relation type filter

limit
integer <int64>

Optional maximum returned rows

Responses

Response samples

Content type
application/json
{
  • "links": [
    ]
}

GET /api/v1/edges/{id} - Get an edge by ID

Authorizations:
api_keybearer_auth
path Parameters
id
required
string

Edge ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "edge_id": "b311b798-212e-414c-ba53-c572923101d4",
  • "edge_type": "supports",
  • "metadata": { },
  • "participants": [
    ],
  • "provenance": {
    },
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "weight": 0
}

DELETE /api/v1/edges/{id} - Delete an edge

Authorizations:
api_keybearer_auth
path Parameters
id
required
string

Edge ID

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

SummarizationPolicies

POST /api/v1/summarization-policies - Create a new summarization policy

Authorizations:
api_keybearer_auth
Request Body schema: application/json
required
create_edges
required
boolean

Whether to create SynthesizedFrom edges

max_sources
required
integer <int32>

Maximum sources to summarize at once

metadata
any

Optional metadata

name
required
string

Policy name

source_level
required
string (AbstractionLevel)
Enum: "raw" "summary" "principle"

Source abstraction level (e.g., Raw/L0)

target_level
required
string (AbstractionLevel)
Enum: "raw" "summary" "principle"

Target abstraction level (e.g., Summary/L1)

trajectory_id
string or null <uuid>

Optional trajectory ID to scope this policy

required
Array of objects or strings or objects or objects or strings (SummarizationTrigger)

Triggers that fire this policy

Responses

Request samples

Content type
application/json
{
  • "create_edges": true,
  • "max_sources": 0,
  • "metadata": null,
  • "name": "string",
  • "source_level": "raw",
  • "target_level": "raw",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "triggers": [
    ]
}

Response samples

Content type
application/json
{
  • "create_edges": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "max_sources": 0,
  • "metadata": { },
  • "name": "string",
  • "source_level": "raw",
  • "summarization_policy_id": "d5e4506d-9171-4b67-8185-83ba27dceeb0",
  • "target_level": "raw",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "triggers": [
    ]
}

GET /api/v1/summarization-policies/{id} - Get a policy by ID

Authorizations:
api_keybearer_auth
path Parameters
id
required
string

Policy ID

Responses

Response samples

Content type
application/json
{
  • "create_edges": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "max_sources": 0,
  • "metadata": { },
  • "name": "string",
  • "source_level": "raw",
  • "summarization_policy_id": "d5e4506d-9171-4b67-8185-83ba27dceeb0",
  • "target_level": "raw",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "triggers": [
    ]
}

DELETE /api/v1/summarization-policies/{id} - Delete a policy

Authorizations:
api_keybearer_auth
path Parameters
id
required
string

Policy ID

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}

GET /api/v1/trajectories/{id}/summarization-policies - List policies for a trajectory

Authorizations:
api_keybearer_auth
path Parameters
id
required
string

Trajectory ID

Responses

Response samples

Content type
application/json
{
  • "policies": [
    ]
}

SummarizationRequests

GET /api/v1/summarization-requests - List summarization requests with optional filters

Authorizations:
api_keybearer_auth
query Parameters
status
string

Filter by status (pending, in_progress, completed, failed)

scope_id
string

Filter by scope ID

summarization_policy_id
string

Filter by policy ID

limit
integer <int64>

Max results (default 50)

offset
integer <int64>

Offset for pagination

Responses

Response samples

Content type
application/json
{
  • "requests": [
    ]
}

GET /api/v1/summarization-requests/{id} - Get a request by ID

Authorizations:
api_keybearer_auth
path Parameters
id
required
string

Summarization Request ID

Responses

Response samples

Content type
application/json
{
  • "completed_at": "2019-08-24T14:15:22Z",
  • "create_edges": true,
  • "max_sources": 0,
  • "metadata": { },
  • "requested_at": "2019-08-24T14:15:22Z",
  • "requested_by": "cda0f200-65cd-4343-aedd-9c936b908826",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "source_level": "raw",
  • "status": "pending",
  • "summarization_policy_id": "d5e4506d-9171-4b67-8185-83ba27dceeb0",
  • "summarization_request_id": "6d29a8f7-a2a8-4c5a-9e9b-61c3fe12a8ee",
  • "target_level": "raw",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "trigger": {
    }
}

PATCH /api/v1/summarization-requests/{id}/status - Update request status

Authorizations:
api_keybearer_auth
path Parameters
id
required
string

Summarization Request ID

Request Body schema: application/json
required
status
required
string (SummarizationRequestStatus)
Enum: "pending" "in_progress" "completed" "failed"

New status for the request

Responses

Request samples

Content type
application/json
{
  • "status": "pending"
}

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "details": { },
  • "message": "string"
}