API docs by Redocly

CELLSTATE API (0.5.7)

Download OpenAPI specification:

URL: https://cellstate.batterypack.dev License: Apache-2.0

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>
description
string or null
metadata
object or null
name
required
string
parent_trajectory_id
string or null <uuid>

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
metadata
object or null
name
string or null
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_server::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_server::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
}

Context

Context assembly, commit, and recall

Assemble context for an LLM prompt.

This endpoint replaces multiple SDK calls with a single server-side assembly that respects token budgets and includes relevant context.

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

Agent ID for multi-agent scenarios

format
string (ContextFormat)
Enum: "markdown" "xml" "json"

Output format for the assembled context

graph_limit
integer or null <int64>

Maximum number of graph links to include

graph_max_depth
integer or null <int32>

Maximum graph traversal depth

graph_rel_types
Array of strings or null

Optional relation type filter for graph traversal

graph_start_id
string or null <uuid>

Optional graph traversal start node override

include_artifacts
boolean

Whether to include recent artifacts

include_graph
boolean

Whether to include graph-derived context hints

include_hierarchy
boolean

Whether to include parent trajectory hierarchy

include_history
boolean

Whether to include scope summaries (compressed history)

include_notes
boolean

Whether to include relevant notes (semantic memory)

include_scoring
boolean or null

Whether to include per-entity scoring debug (all 7 factors) in the response

include_turns
boolean

Whether to include conversation turns from the scope

include_working_set
boolean

Whether to include working-set entries (agent workbench memory)

null or KernelConfigRequest (object)
max_artifacts
integer or null <int32>

Maximum number of artifacts to include

max_notes
integer or null <int32>

Maximum number of notes to include

max_summaries
integer or null <int32>

Maximum number of scope summaries to include

max_turns
integer or null <int32>

Maximum number of turns to include

max_working_set
integer or null <int32>

Maximum number of working-set entries to include

min_relevance
number or null <float>

Minimum relevance score (0.0-1.0) for semantic filtering

relevance_query
string or null

Semantic search query for filtering notes/artifacts by relevance

scope_id
string or null <uuid>

Scope to assemble context for (optional - auto-selects most recent active scope if not provided)

segment_budget
object or null

Optional segment-based token budget allocation.

When provided, segment budgets are enforced in addition to total budget.

token_budget
integer or null <int32>

Maximum token budget for the assembled context

trajectory_id
required
string <uuid>

Trajectory to assemble context for

user_input
string or null

Current user input/query (used for relevance ranking)

Responses

Request samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "format": "markdown",
  • "graph_limit": 0,
  • "graph_max_depth": 0,
  • "graph_rel_types": [
    ],
  • "graph_start_id": "9df5e5ea-be42-440e-8886-b359ee21c957",
  • "include_artifacts": true,
  • "include_graph": true,
  • "include_hierarchy": true,
  • "include_history": true,
  • "include_notes": true,
  • "include_scoring": true,
  • "include_turns": true,
  • "include_working_set": true,
  • "kernel_config": { },
  • "max_artifacts": 0,
  • "max_notes": 0,
  • "max_summaries": 0,
  • "max_turns": 0,
  • "max_working_set": 0,
  • "min_relevance": 0,
  • "relevance_query": "string",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "segment_budget": { },
  • "token_budget": 0,
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "user_input": "string"
}

Response samples

Content type
application/json
{
  • "artifacts_count": 0,
  • "context": "string",
  • "graph_links_count": 0,
  • "hierarchy": [
    ],
  • "included_sections": [
    ],
  • "max_tokens": 0,
  • "notes_count": 0,
  • "scoring_debug": [
    ],
  • "summaries_count": 0,
  • "token_count": 0,
  • "truncated": true,
  • "turns_count": 0,
  • "window_details": { },
  • "working_set_count": 0
}

Commit context to the PCP event DAG for later recall.

Request Body schema: application/json
required
agent_id
string or null <uuid>
content
required
string
metadata
any
mode
string or null
query
string or null
scope_id
required
string <uuid>
tokens_input
integer <int64>
tokens_output
integer <int64>
tools_invoked
Array of strings
trajectory_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "content": "string",
  • "metadata": null,
  • "mode": "string",
  • "query": "string",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "tokens_input": 0,
  • "tokens_output": 0,
  • "tools_invoked": [
    ],
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848"
}

Response samples

Content type
application/json
{
  • "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7"
}

Build a lightweight context outline for progressive disclosure.

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

Agent ID for multi-agent scenarios

format
string (ContextFormat)
Enum: "markdown" "xml" "json"

Output format for the assembled context

graph_limit
integer or null <int64>

Maximum number of graph links to include

graph_max_depth
integer or null <int32>

Maximum graph traversal depth

graph_rel_types
Array of strings or null

Optional relation type filter for graph traversal

graph_start_id
string or null <uuid>

Optional graph traversal start node override

include_artifacts
boolean

Whether to include recent artifacts

include_graph
boolean

Whether to include graph-derived context hints

include_hierarchy
boolean

Whether to include parent trajectory hierarchy

include_history
boolean

Whether to include scope summaries (compressed history)

include_notes
boolean

Whether to include relevant notes (semantic memory)

include_scoring
boolean or null

Whether to include per-entity scoring debug (all 7 factors) in the response

include_turns
boolean

Whether to include conversation turns from the scope

include_working_set
boolean

Whether to include working-set entries (agent workbench memory)

null or KernelConfigRequest (object)
max_artifacts
integer or null <int32>

Maximum number of artifacts to include

max_notes
integer or null <int32>

Maximum number of notes to include

max_summaries
integer or null <int32>

Maximum number of scope summaries to include

max_turns
integer or null <int32>

Maximum number of turns to include

max_working_set
integer or null <int32>

Maximum number of working-set entries to include

min_relevance
number or null <float>

Minimum relevance score (0.0-1.0) for semantic filtering

relevance_query
string or null

Semantic search query for filtering notes/artifacts by relevance

scope_id
string or null <uuid>

Scope to assemble context for (optional - auto-selects most recent active scope if not provided)

segment_budget
object or null

Optional segment-based token budget allocation.

When provided, segment budgets are enforced in addition to total budget.

token_budget
integer or null <int32>

Maximum token budget for the assembled context

trajectory_id
required
string <uuid>

Trajectory to assemble context for

user_input
string or null

Current user input/query (used for relevance ranking)

Responses

Request samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "format": "markdown",
  • "graph_limit": 0,
  • "graph_max_depth": 0,
  • "graph_rel_types": [
    ],
  • "graph_start_id": "9df5e5ea-be42-440e-8886-b359ee21c957",
  • "include_artifacts": true,
  • "include_graph": true,
  • "include_hierarchy": true,
  • "include_history": true,
  • "include_notes": true,
  • "include_scoring": true,
  • "include_turns": true,
  • "include_working_set": true,
  • "kernel_config": { },
  • "max_artifacts": 0,
  • "max_notes": 0,
  • "max_summaries": 0,
  • "max_turns": 0,
  • "max_working_set": 0,
  • "min_relevance": 0,
  • "relevance_query": "string",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "segment_budget": { },
  • "token_budget": 0,
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "user_input": "string"
}

Response samples

Content type
application/json
{
  • "artifact_count": 0,
  • "artifact_names": [
    ],
  • "graph_link_count": 0,
  • "has_kernel_config": true,
  • "has_user_input": true,
  • "hierarchy_depth": 0,
  • "note_count": 0,
  • "note_titles": [
    ],
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "summary_count": 0,
  • "trajectory_id": "60bbb3ae-5c7a-4eeb-b50a-0e5f76826848",
  • "turn_count": 0,
  • "working_set_count": 0
}

Recall previously committed context from the PCP event DAG.

query Parameters
query_text
string

Free-text query for semantic matching

scope_id
string <uuid>

Scope filter

trajectory_id
string <uuid>

Trajectory filter

max_results
integer <int32>

Maximum number of results

recency_weight
number <double>

Weight applied to recency scoring (0.0-1.0)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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",
  • "external_org_id": "string",
  • "name": "string",
  • "settings": { },
  • "status": "active",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

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

SECURITY: Users can only update their own tenant.

Authorizations:
bearer_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",
  • "external_org_id": "string",
  • "name": "string",
  • "settings": { },
  • "status": "active",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

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": [
    ]
}

Working Set

Per-agent key-value working memory

GET /api/v1/working-set - List working-set entries for request principal.

query Parameters
agent_id
string

Filter by agent ID

scope_id
string

Filter by scope ID

limit
integer <int64>

Max results

offset
integer <int64>

Pagination offset

Responses

Response samples

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

PUT /api/v1/working-set - Create or replace a working-set entry.

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

Owning agent.

expires_at
string or null <date-time>

Optional expiry.

key
required
string

Stable key under (tenant_id, agent_id).

metadata
object or null

Optional metadata.

scope_id
string or null <uuid>

Optional scope for this entry.

value
required
object

JSON value for the entry.

Responses

Request samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "key": "string",
  • "metadata": { },
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "value": { }
}

Response samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "key": "string",
  • "metadata": { },
  • "owner_principal_id": "fe39bf7b-6b2d-42fc-be7f-80505e2d7f4f",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "value": { },
  • "version": 0,
  • "working_set_id": "a79ceddf-c6d9-475d-a02a-5558094c8980"
}

GET /api/v1/working-set/{agent_id}/{key} - Fetch one working-set entry.

path Parameters
agent_id
required
string <uuid>

Agent ID

key
required
string

Working set key

Responses

Response samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "key": "string",
  • "metadata": { },
  • "owner_principal_id": "fe39bf7b-6b2d-42fc-be7f-80505e2d7f4f",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "value": { },
  • "version": 0,
  • "working_set_id": "a79ceddf-c6d9-475d-a02a-5558094c8980"
}

DELETE /api/v1/working-set/{agent_id}/{key} - Delete one entry.

path Parameters
agent_id
required
string <uuid>

Agent ID

key
required
string

Working set key

Responses

Response samples

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

PATCH /api/v1/working-set/{agent_id}/{key} - Patch a working-set entry.

path Parameters
agent_id
required
string <uuid>

Agent ID

key
required
string

Working set key

Request Body schema: application/json
required
expires_at
string or null <date-time>

Optional expiry update.

metadata
object or null

Optional metadata update.

scope_id
string or null <uuid>

Optional new scope binding.

value
object or null

Optional new value.

Responses

Request samples

Content type
application/json
{
  • "expires_at": "2019-08-24T14:15:22Z",
  • "metadata": { },
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "value": { }
}

Response samples

Content type
application/json
{
  • "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "key": "string",
  • "metadata": { },
  • "owner_principal_id": "fe39bf7b-6b2d-42fc-be7f-80505e2d7f4f",
  • "scope_id": "5d3fe357-12dd-4f62-b004-6d1fb3b8454f",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "value": { },
  • "version": 0,
  • "working_set_id": "a79ceddf-c6d9-475d-a02a-5558094c8980"
}

Models

Model and provider discovery

GET /api/v1/models - List available models

Returns models from all configured providers, or a single provider if ?provider= is specified.

query Parameters
provider
string

Filter by provider name

Responses

Response samples

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

GET /api/v1/models/providers - List configured providers

Returns all known providers and whether they have API keys configured.

Responses

Response samples

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

Gates

Mutation pipeline gate metadata and analytics

GET /api/v1/gates/metadata - list gate metadata from CELLSTATE.

Responses

Response samples

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

GET /api/v1/gates/stats - tenant-scoped gate analytics from persisted results.

query Parameters
start_time
string

RFC3339 start time

end_time
string

RFC3339 end time

reasons_limit
integer >= 0

Max rejection reasons to return

Responses

Response samples

Content type
application/json
{
  • "by_gate": [
    ],
  • "by_mutation_type": [
    ],
  • "top_rejections": [
    ],
  • "total_mutations": 0,
  • "total_passed": 0,
  • "total_rejected": 0
}

Ingest

Content ingestion into memory

POST /api/v1/ingest

Ingest content into CELLSTATE memory as an artifact.

Supports multiple content types:

  • text: Raw text content
  • url: URL to fetch and extract text from
  • audio: Audio content (base64 encoded or URL reference)
  • image: Image content (base64 encoded or URL reference)
  • video: Video content (base64 encoded or URL reference)
  • screenshot: Screenshot content (base64 encoded)
Request Body schema: application/json
required
null or ArtifactType (string)
content
required
string

The content to ingest (text or URL depending on content_type)

content_type
string (ContentType)
Enum: "text" "url" "audio" "image" "video" "screenshot"

Type of content being ingested

metadata
any

Optional metadata for multimodal content

name
string or null

Optional name for the artifact

scope_id
string or null

Optional scope ID (creates one if not provided)

trajectory_id
string or null

Optional trajectory ID (creates one if not provided)

Responses

Request samples

Content type
application/json
{
  • "artifact_type": { },
  • "content": "string",
  • "content_type": "text",
  • "metadata": null,
  • "name": "string",
  • "scope_id": "string",
  • "trajectory_id": "string"
}

Response samples

Content type
application/json
{
  • "artifact_id": "string",
  • "scope_id": "string",
  • "trajectory_id": "string"
}

Bash

Bash execution reporting and sandboxed execution

POST /api/v1/bash/execute - execute a command in the server sandbox.

Request Body schema: application/json
required
args
Array of strings

Optional explicit args.

command
required
string

Command binary or command line.

object

Optional environment overrides (filtered by sandbox policy).

isolation_level
string or null

Optional isolation level override: audit or process.

max_output_bytes
integer or null <int64> >= 0

Optional output cap override in bytes.

memory_bytes
integer or null <int64> >= 0

Optional memory limit override in bytes.

timeout_ms
integer or null <int64> >= 0

Optional timeout override in milliseconds.

Responses

Request samples

Content type
application/json
{
  • "args": [
    ],
  • "command": "string",
  • "env": {
    },
  • "isolation_level": "string",
  • "max_output_bytes": 0,
  • "memory_bytes": 0,
  • "timeout_ms": 0
}

Response samples

Content type
application/json
{
  • "duration_ms": 0,
  • "exit_code": 0,
  • "resource_violations": [
    ],
  • "stderr": "string",
  • "stdout": "string",
  • "timed_out": true
}

GET /api/v1/bash/executions - list completed bash executions for this tenant.

query Parameters
trajectory_id
string

Filter by trajectory

scope_id
string

Filter by scope

agent_id
string

Filter by agent

limit
integer >= 0

Max results

offset
integer >= 0

Pagination offset

Responses

Response samples

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

POST /api/v1/bash/report - append a bash execution event to the EventDag.

Request Body schema: application/json
required
agent_id
required
string
command
required
string
duration_ms
required
integer <int64> >= 0
exit_code
required
integer <int32>
Array of objects or null (ReportFileMutation)
files_modified
required
Array of strings
scope_id
required
string
session_id
required
string
source_turn
integer or null <int32>
stderr_preview
required
string
stdout_preview
required
string
timed_out
required
boolean
trajectory_id
required
string

Responses

Request samples

Content type
application/json
{
  • "agent_id": "string",
  • "command": "string",
  • "duration_ms": 0,
  • "exit_code": 0,
  • "file_mutations": [
    ],
  • "files_modified": [
    ],
  • "scope_id": "string",
  • "session_id": "string",
  • "source_turn": 0,
  • "stderr_preview": "string",
  • "stdout_preview": "string",
  • "timed_out": true,
  • "trajectory_id": "string"
}

Response samples

Content type
application/json
{
  • "classification": { },
  • "event_id": "string",
  • "has_mutations": true,
  • "mutation_receipts": [
    ],
  • "parsed_output": { }
}

Browser

Browser action reporting

POST /api/v1/browser/report — append a browser action event to the EventDag.

Request Body schema: application/json
required
action
required
string
duration_ms
required
integer <int64> >= 0
error
string or null
navigation_count
integer or null <int32> >= 0
result_summary
required
any
screenshot
string or null
session_id
required
string
success
required
boolean
url
string or null

Responses

Request samples

Content type
application/json
{
  • "action": "string",
  • "duration_ms": 0,
  • "error": "string",
  • "navigation_count": 0,
  • "result_summary": null,
  • "screenshot": "string",
  • "session_id": "string",
  • "success": true,
  • "url": "string"
}

Response samples

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

A2A

Agent-to-agent task lifecycle and discovery

GET `/.well-known/agent.json` — A2A Agent Card discovery.

Unauthenticated per the A2A spec: any client must be able to discover capabilities without presenting credentials.

Responses

POST /api/v1/a2a/tasks — submit a new A2A task.

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

Arbitrary JSON input.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "error_message": "string",
  • "input": { },
  • "output": { },
  • "status": "submitted",
  • "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "updated_at": "2019-08-24T14:15:22Z"
}

GET /api/v1/a2a/tasks/{task_id} — fetch task state.

Authorizations:
api_keybearer_auth
path Parameters
task_id
required
string

Task ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "error_message": "string",
  • "input": { },
  • "output": { },
  • "status": "submitted",
  • "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "updated_at": "2019-08-24T14:15:22Z"
}

POST /api/v1/a2a/tasks/{task_id}/cancel — cancel an in-progress task.

The route now composes through the mutation pipeline so cancellation emits the same receipt/event semantics as other stateful mutations.

Authorizations:
api_keybearer_auth
path Parameters
task_id
required
string

Task ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "error_message": "string",
  • "input": { },
  • "output": { },
  • "status": "submitted",
  • "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "updated_at": "2019-08-24T14:15:22Z"
}

POST /api/v1/a2a/tasks/{task_id}/complete — complete task with output.

Authorizations:
api_keybearer_auth
path Parameters
task_id
required
string

Task ID

Request Body schema: application/json
required
output
required
object

Task output.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "error_message": "string",
  • "input": { },
  • "output": { },
  • "status": "submitted",
  • "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "updated_at": "2019-08-24T14:15:22Z"
}

GET /api/v1/a2a/tasks/{task_id}/events — SSE stream of task status events.

Emits the current task state immediately, then polls every second for state changes. The stream closes automatically once the task reaches a terminal state (completed, canceled, or failed).

Authorizations:
api_keybearer_auth
path Parameters
task_id
required
string

Task ID

Responses

POST /api/v1/a2a/tasks/{task_id}/fail — fail task with error message.

Authorizations:
api_keybearer_auth
path Parameters
task_id
required
string

Task ID

Request Body schema: application/json
required
error_message
required
string

Human-readable error description.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "error_message": "string",
  • "input": { },
  • "output": { },
  • "status": "submitted",
  • "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "updated_at": "2019-08-24T14:15:22Z"
}

POST /api/v1/a2a/tasks/{task_id}/start — transition task to working.

Authorizations:
api_keybearer_auth
path Parameters
task_id
required
string

Task ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "error_message": "string",
  • "input": { },
  • "output": { },
  • "status": "submitted",
  • "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "updated_at": "2019-08-24T14:15:22Z"
}

A2UI

Agent-to-UI state streaming and render surface

POST `/a2ui/state` — Write component state and compute incremental patches.

Accepts a full property snapshot for a component instance. On first write, stores the snapshot and returns version 1 with no patches (full state is the baseline). On subsequent writes, computes JSON Patch (RFC 6902) diffs against the previous state and broadcasts changes to SSE subscribers.

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

Component instance ID.

props
required
any

Current component properties (full snapshot).

Responses

Request samples

Content type
application/json
{
  • "instanceId": "string",
  • "props": null
}

Response samples

Content type
application/json
{
  • "instanceId": "string",
  • "patches": [
    ],
  • "version": 0
}

GET `/a2ui/subscribe` — SSE stream of component state changes.

Subscribes to the A2UI broadcast channel and emits JSON Patch events as they arrive. Each event contains the instance_id, version, and patch operations.

On connection, emits an initial state_snapshot SSE event containing the full current state of all component instances for the authenticated tenant. This allows late-joining subscribers to bootstrap their local state before receiving incremental patches.

Authorizations:
api_keybearer_auth

Responses

AgUi

AG-UI SSE protocol surface

Stream AG-UI protocol events

SSE endpoint that streams AG-UI protocol events for a given trajectory. Subscribes to internal event bus, filters by tenant and trajectory, and transforms events into AG-UI format.

query Parameters
trajectory_id
required
string

Trajectory ID (UUID) to stream events for

Responses

MCP

Model Context Protocol — tools, resources, prompts, logging

POST /mcp/completion/complete - Autocomplete prompt arguments

Request Body schema: application/json
required
required
object (CompletionArgument)

The argument being completed

required
object or object (CompletionReference)

Responses

Request samples

Content type
application/json
{
  • "argument": {
    },
  • "ref": {
    }
}

Response samples

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

POST /mcp/logging/setLevel - Set the server-side log level

Request Body schema: application/json
required
level
required
string (LoggingLevel)
Enum: "emergency" "alert" "critical" "error" "warning" "notice" "info" "debug"

The log level to set

Responses

Request samples

Content type
application/json
{
  • "level": "emergency"
}

Response samples

Content type
application/json
{
  • "level": "emergency"
}

POST /mcp/tools/list - List available tools

Responses

Response samples

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

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"
}