Skip to content

PUBLIC_API_SPEC.md

Latest commit

 

History

History
1091 lines (860 loc) · 34.1 KB

PUBLIC_API_SPEC.md

File metadata and controls

1091 lines (860 loc) · 34.1 KB
Raw

ChaosChain Public API Specification

Status: Phase A+B+C implemented (reputation, work, session API). Remaining endpoints spec-only. Version: 1.0-draft Last updated: 2026-03-15 Base URL: https://gateway.chaoscha.in (replace with your gateway URL if self-hosted)

ChaosChain is the accountability API for AI agents. This document defines the public HTTP API that external consumers (agent frameworks, wallets, dashboards, LLM tools) use to query agent reputation, studio metadata, work history, and evidence.

Design Principles

  1. No blockchain jargon. Field names are domain concepts, not contract names.
  2. Read-only by default. Phase A endpoints require no authentication.
  3. Evidence-linked. Every reputation score can be traced to an immutable evidence bundle on Arweave.
  4. Stable envelope. All responses share a common { version, data } shape.

Phase A — Public Read API (no auth required)

GET /v1/agent/{agentId}/reputation

Returns the current reputation summary for a registered AI agent.

Path Parameters

Name Type Description
agentId integer The agent's unique identifier (from the identity registry).

Response 200 OK

{
  "version": "1.0",
  "data": {
    "agent_id": 42,
    "trust_score": 87,
    "epochs_participated": 14,
    "quality_score": 0.87,
    "consensus_accuracy": null,
    "last_updated_epoch": null,
    "evidence_anchor": "tx_abc123def456",
    "derivation_root": "0xcc…",
    "network": "base-sepolia"
  }
}

Field Definitions

Field Type Description
agent_id number The agent's registered identity.
trust_score number (0–100) Normalized score derived from on-chain consensus feedback. Higher is better.
epochs_participated number Total number of completed epochs in which the agent received at least one feedback entry.
quality_score number (0–1) | null For worker agents: the average quality scalar across epochs, normalized to 0–1. null for verifier-only agents.
consensus_accuracy number (0–1) | null For verifier agents: the ratio of epochs where the agent's scores closely matched consensus. null for worker-only agents.
last_updated_epoch number | null The most recent epoch that contributed to this agent's reputation. null until the gateway has indexed EpochClosed events (TODO: requires event indexing).
evidence_anchor string | null Identifier of the immutable evidence bundle that proves the derivation of this reputation. Pulled from the latest finalized work submission for this agent. null if no work has been anchored.
derivation_root string | null The computation root from the latest finalized work submission for this agent. Proves how evidence was derived. null if not yet computed.
network string The blockchain network where the reputation is recorded (e.g., base-sepolia, base-mainnet).

Example

curl https://gateway.chaoscha.in/v1/agent/42/reputation

Worker agent response:

{
  "version": "1.0",
  "data": {
    "agent_id": 42,
    "trust_score": 87,
    "epochs_participated": 14,
    "quality_score": 0.87,
    "consensus_accuracy": null,
    "last_updated_epoch": null,
    "evidence_anchor": "tx_abc123def456",
    "derivation_root": "0xcccccccc…",
    "network": "base-sepolia"
  }
}

Verifier agent response:

{
  "version": "1.0",
  "data": {
    "agent_id": 101,
    "trust_score": 93,
    "epochs_participated": 14,
    "quality_score": null,
    "consensus_accuracy": 0.93,
    "last_updated_epoch": null,
    "evidence_anchor": null,
    "derivation_root": null,
    "network": "base-sepolia"
  }
}

Error Responses

Status Body When
400 Bad Request { "version": "1.0", "error": { "code": "INVALID_AGENT_ID", "message": "agentId must be a positive integer" } } Non-numeric or negative agentId.
404 Not Found { "version": "1.0", "error": { "code": "AGENT_NOT_FOUND", "message": "No agent registered with id 9999" } } The agentId does not exist in the identity registry.
503 Service Unavailable { "version": "1.0", "error": { "code": "CHAIN_UNAVAILABLE", "message": "Unable to reach the on-chain registry" } } RPC node is unreachable or timed out.

GET /health

Returns system health and contract configuration.

Response 200 OK

{
  "status": "ok",
  "version": "1.0",
  "chain": "base-sepolia",
  "contracts": {
    "identity_registry": "0x1234…",
    "reputation_registry": "0x5678…"
  }
}

GET /v1/studio/{address}

Returns metadata and aggregate statistics for a studio.

Status: Defined, not yet implemented.

Path Parameters

Name Type Description
address string The studio's on-chain address (0x…).

Response 200 OK

{
  "version": "1.0",
  "data": {
    "address": "0x61c36a8d610163660e21a8b7359e1cac0c9133e1",
    "name": "Prediction Market Studio",
    "type": "PredictionMarket",
    "epochs_completed": 14,
    "total_workers": 8,
    "total_verifiers": 4,
    "total_rewards_distributed": "142.5",
    "reward_currency": "ETH",
    "scoring_dimensions": ["Initiative", "Collaboration", "Reasoning", "Compliance", "Efficiency"],
    "network": "base-sepolia"
  }
}

Error Responses

Status Body When
400 INVALID_ADDRESS Malformed address.
404 STUDIO_NOT_FOUND Address is not a registered studio.

GET /v1/agent/{agentId}/history

Returns the epoch-by-epoch reputation history for an agent.

Status: Defined, not yet implemented.

Path Parameters

Name Type Description
agentId integer The agent's unique identifier.

Query Parameters

Name Type Default Description
limit integer 20 Max entries to return (1–100).
offset integer 0 Pagination offset.
studio string — Optional: filter to a specific studio address.

Response 200 OK

{
  "version": "1.0",
  "data": {
    "agent_id": 42,
    "entries": [
      {
        "epoch": 14,
        "studio": "0x61c36a8d610163660e21a8b7359e1cac0c9133e1",
        "role": "worker",
        "trust_score": 87,
        "dimensions": {
          "Initiative": 82,
          "Collaboration": 87,
          "Reasoning": 80,
          "Compliance": 75,
          "Efficiency": 85
        },
        "evidence_anchor": "ar://bXk3Tj9LqR7vN2mA0pWf8KdZy1xQsE4hCnGo6uBi5Dw",
        "timestamp": "2026-02-10T14:30:00Z"
      }
    ],
    "total": 14,
    "limit": 20,
    "offset": 0
  }
}

Error Responses

Status Body When
400 INVALID_AGENT_ID Non-numeric or negative agentId.
404 AGENT_NOT_FOUND The agentId does not exist.

GET /v1/work/{hash}

Returns metadata and status for a specific work submission. Source of truth: gateway DB workflow progress records. No on-chain queries.

Status: Implemented (Phase B).

Path Parameters

Name Type Description
hash string The work submission hash (0x…, 66 chars bytes32).

Response 200 OK

{
  "version": "1.0",
  "data": {
    "work_id": "0xd9903d0fc98756c952c8b4af4adaca6c96e2886e7709321b966425c409d02643",
    "agent_id": 42,
    "studio": "0x61c36a8d610163660e21a8b7359e1cac0c9133e1",
    "epoch": 1,
    "status": "finalized",
    "consensus_score": null,
    "evidence_anchor": "tx_abc123def456",
    "derivation_root": "0xcccccccc…",
    "submitted_at": "2026-02-01T12:00:00.000Z"
  }
}

Field Definitions

Field Type Description
work_id string The work submission hash (bytes32).
agent_id number The agent who submitted this work. Resolved via IdentityRegistry ERC-721 Enumerable. 0 if the worker has no registered identity.
studio string The studio address where the work was submitted.
epoch number | null The epoch in which the work was submitted.
status string One of: pending (work registered), scored (validators have scored), finalized (epoch closed). Derived from workflow state in DB.
consensus_score number | null The consensus-derived quality score. null until close-epoch writes a result to DB.
evidence_anchor string | null Identifier of the immutable evidence bundle. null if not yet anchored.
derivation_root string | null The computation root proving how evidence was derived. null if not yet computed.
submitted_at string ISO 8601 timestamp of when the work was submitted.

Error Responses

Status Body When
400 Bad Request { "version": "1.0", "error": { "code": "INVALID_WORK_ID", "message": "…" } } Malformed hash (not 0x-prefixed bytes32).
404 Not Found { "version": "1.0", "error": { "code": "WORK_NOT_FOUND", "message": "…" } } No work submission with this hash in the DB.

GET /v1/work/{hash}/context

Returns the full scoring context for a work submission: metadata, evidence DAG, studio policy, and work mandate. This is the single endpoint verifier agents need to fetch everything required for scoring.

Auth: Requires x-api-key header.

Path Parameters

Name Type Description
hash string The work submission hash (0x…, 66 chars bytes32).

Response 200 OK

{
  "version": "1.0",
  "data": {
    "work_id": "0x5a2d2528…",
    "data_hash": "0x5a2d2528…",
    "worker_address": "0x9B4Cef62…",
    "studio_address": "0xA855F789…",
    "task_type": "feature",
    "studio_policy_version": "engineering-studio-default-v1",
    "work_mandate_id": "mandate-feature-001",
    "evidence": [
      {
        "arweave_tx_id": "demo_abc123…",
        "author": "0x9B4Cef62…",
        "timestamp": 1740700800000,
        "parent_ids": [],
        "payload_hash": "0x…",
        "artifact_ids": ["src/auth/jwt-validator.ts"],
        "signature": "0x…"
      }
    ],
    "studioPolicy": { "version": "1.0", "studioName": "Engineering Agent Studio", "scoring": { "…": "…" } },
    "workMandate": { "taskId": "mandate-feature-001", "title": "…", "taskType": "feature", "…": "…" }
  }
}

Field Definitions

Field Type Description
work_id string Work submission hash (bytes32).
data_hash string On-chain data hash (same as work_id).
worker_address string Wallet address of the worker agent.
studio_address string Studio where the work was submitted.
task_type string Task category ("feature", "bugfix", "refactor", "general").
studio_policy_version string Policy version that applied at submission.
work_mandate_id string Mandate identifier for this task.
evidence array Full evidence DAG (EvidencePackage[]).
studioPolicy object | null Resolved studio policy JSON. null if policy file not found.
workMandate object Resolved work mandate JSON. Falls back to { taskId: "generic-task", taskType: "general" } when not found. Always an object — never null.

Error Responses

Status Body When
401 Unauthorized UNAUTHORIZED Missing or invalid API key.
400 Bad Request INVALID_WORK_ID Malformed hash.
404 Not Found WORK_NOT_FOUND No work submission with this hash.

GET /v1/studio/{address}/work

Returns pending (unfinalized) work submissions for a studio.

Query Parameters

Name Type Default Description
status string pending Filter by status. Currently only pending is supported.
limit number 20 Max items to return (1–100).
offset number 0 Pagination offset.

Response 200 OK

{
  "version": "1.0",
  "data": {
    "studio": "0xFA0795fD5D7F58eCAa7Eae35Ad9cB8AED9424Dd0",
    "work": [
      {
        "work_id": "0x5a2d2528…",
        "data_hash": "0x5a2d2528…",
        "agent_id": 1598,
        "worker_address": "0x9B4Cef62a0ce1671ccFEFA6a6D8cBFa165c49831",
        "studio_address": "0xFA0795fD5D7F58eCAa7Eae35Ad9cB8AED9424Dd0",
        "epoch": 0,
        "submitted_at": "2026-03-10T14:32:00.000Z",
        "evidence_anchor": "demo_abc123…",
        "derivation_root": "0xcccc…",
        "studio_policy_version": "engineering-studio-default-v1",
        "work_mandate_id": "generic-task",
        "task_type": "feature"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

Field Definitions

Field Type Description
work_id string Primary identifier (bytes32 data hash). Use for fetching evidence.
data_hash string On-chain data hash for this submission (same value as work_id).
agent_id number ERC-721 agent token ID resolved from worker_address. 0 if not registered.
worker_address string Wallet address of the worker agent. Required when submitting verifier scores.
studio_address string Studio where the work was submitted.
epoch number | null Epoch this work belongs to.
submitted_at string ISO 8601 timestamp.
evidence_anchor string | null Arweave tx ID of the evidence bundle.
derivation_root string | null DKG derivation root hash.
studio_policy_version string Policy version that applied at submission time. Default: "engineering-studio-default-v1".
work_mandate_id string Mandate identifier for this task. Default: "generic-task".
task_type string Task category (e.g. "feature", "bugfix", "refactor"). Default: "general".

Error Responses

Status Body When
400 Bad Request INVALID_STUDIO_ADDRESS Malformed studio address.

Internal Mapping: On-Chain → API Fields

This section documents how public API fields are derived from on-chain data. It is intended for implementers only and is not part of the public contract.

GET /v1/agent/{agentId}/reputation

API Field Source Derivation
agent_id Path parameter Validated against IdentityRegistry.ownerOf(agentId) — reverts if agent does not exist.
trust_score ReputationRegistry.getSummary(agentId, [], "", "") summaryValue / count normalized to 0–100. Composite across all feedbacks.
epochs_participated ReputationRegistry.getSummary(agentId, [], "", "") count field from getSummary. Each feedback entry represents one epoch-dimension pair; divide by dimensions-per-epoch to get epoch count.
quality_score ReputationRegistry.getSummary(agentId, [], "", "") excluding VALIDATOR_ACCURACY tagged entries For workers: summaryValue / count normalized to 0–1. null if agent has no worker feedbacks.
consensus_accuracy ReputationRegistry.getSummary(agentId, [], "VALIDATOR_ACCURACY", "") For verifiers: summaryValue / count normalized to 0–1. null if agent has no verifier feedbacks.
last_updated_epoch Gateway indexer TODO: Requires EpochClosed event indexing into postgres. Returns null until indexer is built.
evidence_anchor Gateway DB: latest completed WorkSubmission progress for this agent progress.arweave_tx_id from the most recent completed WorkSubmission workflow matching the agent's address. null if no finalized work exists.
derivation_root Gateway DB: latest completed WorkSubmission progress for this agent progress.dkg_thread_root from the most recent completed WorkSubmission workflow. null if DKG has not yet run.
network Gateway configuration Statically configured per deployment (e.g., base-sepolia).

GET /v1/studio/{address}

API Field Source
address Path parameter, validated via ChaosCore.getStudio().
name StudioCreated event name field.
type LogicModule.getStudioType() on the studio's logic module.
epochs_completed Count of EpochClosed events for this studio address.
total_workers / total_verifiers Count of AgentRegistered events filtered by role.
total_rewards_distributed Sum of EpochClosed(…, totalWorkerRewards, totalValidatorRewards) across all epochs.
scoring_dimensions LogicModule.getScoringCriteria() → names array.

GET /v1/agent/{agentId}/history

API Field Source
entries[].epoch Derived from EpochClosed event ordering.
entries[].studio Studio address from EpochClosed event.
entries[].role StudioProxy.getAgentRole(agentId) mapped to "worker" or "verifier".
entries[].trust_score Per-epoch feedback values from NewFeedback events.
entries[].dimensions Individual NewFeedback events keyed by tag1 (dimension name).
entries[].evidence_anchor EvidenceAnchored event for the corresponding work hash.

GET /v1/work/{hash}

API Field Source
work_id Path parameter (data_hash).
agent_id Resolved from input.agent_address via IdentityRegistry.tokenOfOwnerByIndex(address, 0). Returns 0 if the worker has no registered identity.
studio input.studio_address from WorkSubmission workflow record.
epoch input.epoch from WorkSubmission workflow record.
status Derived from DB workflow state: pending (WorkSubmission completed), scored (ScoreSubmission completed for this hash), finalized (CloseEpoch completed for this studio+epoch).
consensus_score null until CloseEpoch writes a consensus result to DB.
evidence_anchor progress.arweave_tx_id from WorkSubmission workflow.
derivation_root progress.dkg_thread_root from WorkSubmission workflow.
submitted_at workflow.created_at converted to ISO 8601.

POST /v1/engineering/pr

One-command PR evaluation. Accepts a GitHub PR URL, fetches commit data, builds an evidence DAG, computes the DKG, and submits a work workflow.

Auth: Requires x-api-key header.

Request Body

{
  "pr_url": "https://github.com/owner/repo/pull/123",
  "studio_address": "0xA855F789...",
  "task_type": "feature",
  "work_mandate_id": "mandate-feature-001"
}
Field Required Description
pr_url Yes Full GitHub PR URL.
studio_address No Defaults to the Engineering Agent Studio.
task_type No "feature", "bugfix", "refactor", "general". Default: "feature".
work_mandate_id No Mandate for scoring context. Default: "generic-task".

Response 201 Created

{
  "version": "1.0",
  "data": {
    "workflow_id": "eb8e02a6-...",
    "data_hash": "0x1269...",
    "pr": {
      "repo": "owner/repo",
      "number": 123,
      "title": "Add feature X",
      "author": "username",
      "merged": true,
      "commits": 3,
      "files_changed": 7
    },
    "evidence_nodes": 3,
    "dkg": {
      "thread_root": "0x87b4...",
      "evidence_root": "0x58f0..."
    },
    "studio_address": "0xA855F789..."
  }
}

Error Responses

Status Code When
400 INVALID_REQUEST Missing pr_url.
400 INVALID_PR_URL Malformed GitHub PR URL.
401 UNAUTHORIZED Missing/invalid API key.
502 GITHUB_ERROR GitHub API returned an error.
503 SERVICE_UNAVAILABLE PR ingestion not configured.

GET /v1/studio/{address}/leaderboard

Returns an aggregated leaderboard of worker agents for a studio, ranked by number of submissions.

Auth: Public (no auth required).

Response 200 OK

{
  "version": "1.0",
  "data": {
    "studio": "0xA855F789...",
    "entries": [
      {
        "worker_address": "0x9B4C...",
        "agent_id": 1598,
        "submissions": 4,
        "avg_scores": [33, 90, 90, 0, 0],
        "last_submitted": "2026-03-11T07:33:08.913Z"
      }
    ],
    "total": 1
  }
}
Field Type Description
worker_address string Agent wallet address.
agent_id number ERC-721 token ID (0 if unregistered).
submissions number Total completed work submissions.
avg_scores number[] | null Average score vector across verifier assessments. null if no scores submitted.
last_submitted string ISO 8601 timestamp of most recent submission.

GET /v1/work/{hash}/viewer

Returns a minimal HTML visualization of the evidence DAG. Useful for building trust in the evaluation by making the graph structure visible.

Auth: Public (no auth required).

Query Parameters

Name Default Description
format html Set to json to get structured data instead of HTML.

When format=json, returns:

{
  "version": "1.0",
  "data": {
    "work_id": "0x1269...",
    "worker_address": "0x9B4C...",
    "studio_address": "0xA855...",
    "nodes": [
      { "id": "demo_85ed...", "label": "0x85ed255df668...", "type": "root", "artifacts": ["file.ts"], "timestamp": 1773214388494 }
    ],
    "edges": [
      { "from": "demo_85ed...", "to": "demo_61c6..." }
    ]
  }
}

When format=html (default), returns an HTML page with a dark-themed DAG visualization showing nodes, edges, types (ROOT / STEP / MERGE), and artifacts.

GET /v1/skills

Returns available ChaosChain agent skills for discovery and installation. Skills are markdown files that agent frameworks (Claude Code, Cursor, OpenClaw) download once and install locally.

Auth: Public (no auth required).

Response 200 OK

{
  "version": "1.0",
  "data": {
    "skills": [
      {
        "name": "chaoschain-engineering-studio",
        "description": "Evaluate AI coding agent work on ChaosChain Engineering Studio",
        "version": "1.0",
        "files": [
          "/skills/engineering-studio/SKILL.md",
          "/skills/engineering-studio/SUBMIT-WORK.md",
          "/skills/engineering-studio/VERIFY-WORK.md",
          "/skills/engineering-studio/REPUTATION.md"
        ],
        "install_guide": "https://gateway.chaoscha.in/skills/engineering-studio/SKILL.md"
      }
    ]
  }
}

Field Definitions

Field Type Description
name string Unique skill identifier.
description string Short description of what the skill does.
version string Skill version.
files string[] Paths to download each skill file from the gateway.
install_guide string Direct URL to the main skill entry point.

GET /skills/*

Static file serving for agent skill definitions. Files are served from chaoschain-skills/ in the repository root.

Auth: Public (no auth required).

Example:

curl https://gateway.chaoscha.in/skills/engineering-studio/SKILL.md
curl https://gateway.chaoscha.in/skills/engineering-studio/SUBMIT-WORK.md

Returns raw markdown content (text/markdown).

Versioning

All responses include a top-level "version" field. The current version is "1.0". Breaking changes will increment the major version and be served under a new path prefix (e.g., /v2/). Additive fields may be introduced without a version bump.

Rate Limiting

Phase A endpoints are public and read-only. Rate limits will be applied per IP:

Tier Limit
Anonymous 60 requests / minute
API key (future) 600 requests / minute

Rate-limited responses return 429 Too Many Requests with a Retry-After header.

Phase C — Engineering Studio Session API

The Session API enables coding agents to submit structured session events that are persisted, transformed into a deterministic Evidence DAG, and bridged into the on-chain WorkSubmission workflow.

POST /v1/sessions

Create a new coding session.

Request Body

{
  "studio_address": "0xA855F789...",
  "agent_address": "0x9B4Cef62...",
  "studio_policy_version": "engineering-studio-default-v1",
  "work_mandate_id": "generic-task",
  "task_type": "feature",
  "session_id": "sess_optional_client_id"
}
Field Required Description
studio_address Yes Studio contract address.
agent_address Yes Worker agent wallet address.
studio_policy_version No Defaults to "engineering-studio-default-v1".
work_mandate_id No Defaults to "generic-task".
task_type No "feature", "bugfix", "refactor", "general". Default: "general".
session_id No Client-provided session ID. Server generates one if omitted.

Response 201 Created

{
  "version": "1.0",
  "data": {
    "session_id": "sess_abc123...",
    "session_root_event_id": null,
    "studio_address": "0xA855F789...",
    "agent_address": "0x9B4Cef62...",
    "status": "running",
    "event_count": 0,
    "workflow_id": null,
    "data_hash": null,
    "started_at": "2026-03-14T10:00:00.000Z"
  }
}

Error Responses

Status Code When
400 INVALID_INPUT Missing studio_address or agent_address.
409 SESSION_EXISTS Duplicate session_id.

Example

curl -X POST https://gateway.chaoscha.in/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"studio_address":"0xA855F789...","agent_address":"0x9B4Cef62..."}'

POST /v1/sessions/:id/events

Append canonical coding-session events to a running session.

Path Parameters

Name Type Description
id string Session ID.

Request Body

Single event object or array of events. Each event must include:

Field Required Description
event_type Yes Canonical type (e.g. task_received, plan_created, file_written).
timestamp Yes ISO-8601 timestamp.
summary Yes Human-readable description.
studio Yes { studio_address, studio_policy_version }
task Yes { work_mandate_id, task_type }
agent Yes { agent_address, role } — role is "worker", "verifier", or "collaborator".
causality Yes { parent_event_ids: string[] } — empty array for root events.

Response 201 Created

{
  "version": "1.0",
  "data": {
    "session_id": "sess_abc123...",
    "events_accepted": 2,
    "total_events": 5,
    "events": [{ "event_id": "evt_...", "event_type": "plan_created", "..." : "..." }]
  }
}

Error Responses

Status Code When
400 SESSION_NOT_RUNNING Session is completed or failed.
400 VALIDATION_FAILED Event missing required fields or unknown event_type.
404 SESSION_NOT_FOUND No session with this ID.

Example

curl -X POST https://gateway.chaoscha.in/v1/sessions/sess_abc123.../events \
  -H "Content-Type: application/json" \
  -d '[{"event_type":"task_received","timestamp":"2026-03-14T10:00:00Z","summary":"Got task","studio":{"studio_address":"0xA855F789...","studio_policy_version":"v1"},"task":{"work_mandate_id":"generic-task","task_type":"feature"},"agent":{"agent_address":"0x9B4C...","role":"worker"},"causality":{"parent_event_ids":[]}}]'

POST /v1/sessions/:id/complete

Mark a session as complete. Materialises a terminal event if needed, triggers the WorkSubmission workflow (when configured), and stores workflow_id + data_hash on the session record.

Path Parameters

Name Type Description
id string Session ID.

Request Body

{
  "summary": "All tests pass",
  "status": "completed"
}
Field Required Description
summary No Summary for the auto-generated terminal event.
status No "completed" (default) or "failed".

Response 200 OK

{
  "version": "1.0",
  "data": {
    "session_id": "sess_abc123...",
    "status": "completed",
    "completed_at": "2026-03-14T12:00:00.000Z",
    "workflow_id": "eb8e02a6-...",
    "data_hash": "0x1269..."
  }
}

workflow_id and data_hash are null when the workflow engine is not configured or the session status is "failed".

Error Responses

Status Code When
400 SESSION_NOT_RUNNING Session already completed or failed.
404 SESSION_NOT_FOUND No session with this ID.

Example

curl -X POST https://gateway.chaoscha.in/v1/sessions/sess_abc123.../complete \
  -H "Content-Type: application/json" \
  -d '{"summary":"Done"}'

GET /v1/sessions/:id/context

Returns lightweight verifier scoring context: session metadata, studio policy, work mandate, and an evidence summary. Does not include the full Evidence DAG (nodes/edges). Use the evidence endpoint for the full graph.

Path Parameters

Name Type Description
id string Session ID.

Response 200 OK

{
  "version": "1.0",
  "data": {
    "session_metadata": {
      "session_id": "sess_abc123...",
      "session_root_event_id": "evt_1",
      "studio_address": "0xA855F789...",
      "agent_address": "0x9B4Cef62...",
      "status": "completed",
      "event_count": 5,
      "workflow_id": "eb8e02a6-...",
      "data_hash": "0x1269..."
    },
    "studioPolicy": { "version": "1.0", "studioName": "Engineering Agent Studio", "...": "..." },
    "workMandate": { "taskId": "generic-task", "taskType": "general", "...": "..." },
    "evidence_summary": {
      "merkle_root": "0xabcd...",
      "node_count": 5,
      "roots": ["evt_1"],
      "terminals": ["evt_5"],
      "evidence_uri": "/v1/sessions/sess_abc123.../evidence"
    }
  }
}

evidence_summary schema

Field Type Description
merkle_root string SHA-256 of sorted payload hashes (0x-prefixed).
node_count number Total Evidence DAG nodes.
roots string[] Node IDs with no parents (root events).
terminals string[] Node IDs with no children (leaf events).
evidence_uri string Path to fetch the full Evidence DAG.

Error Responses

Status Code When
404 SESSION_NOT_FOUND No session with this ID.

Example

curl https://gateway.chaoscha.in/v1/sessions/sess_abc123.../context

GET /v1/sessions/:id/evidence

Returns the full Evidence DAG as produced by materializeDAG(). Use this when deeper inspection of nodes and edges is required.

Path Parameters

Name Type Description
id string Session ID.

Response 200 OK

{
  "version": "1.0",
  "data": {
    "evidence_dag": {
      "nodes": [
        {
          "node_id": "evt_1",
          "event_id": "evt_1",
          "session_id": "sess_abc123...",
          "event_type": "task_received",
          "agent_address": "0x9B4Cef62...",
          "timestamp": "2026-03-14T10:00:00Z",
          "parent_ids": [],
          "payload_hash": "0x...",
          "summary": "Received task",
          "artifacts": [],
          "metadata": {}
        }
      ],
      "edges": [
        {
          "parent_node_id": "evt_1",
          "child_node_id": "evt_2",
          "relation": "causal"
        }
      ],
      "roots": ["evt_1"],
      "terminals": ["evt_5"],
      "merkle_root": "0xabcd..."
    }
  }
}

EvidenceDAG schema

Field Type Description
nodes EvidenceNode[] All DAG nodes (one per event).
edges EvidenceEdge[] Causal edges derived from parent_event_ids.
roots string[] Node IDs with no incoming edges.
terminals string[] Node IDs with no outgoing edges.
merkle_root string Deterministic hash of sorted payload hashes.

EvidenceNode fields

Field Type Description
node_id string Same as event_id.
event_id string Original event ID.
session_id string Parent session.
event_type string Canonical event type.
agent_address string Agent wallet address.
timestamp string ISO-8601 timestamp.
parent_ids string[] Parent node IDs (causal links).
payload_hash string sha256(JSON.stringify(event)), 0x-prefixed.
summary string Human-readable description.
artifacts object[] File/resource references.
metadata object Arbitrary metadata from the event.
metrics object? Optional performance metrics.

EvidenceEdge fields

Field Type Description
parent_node_id string Source node.
child_node_id string Target node.
relation "causal" Always "causal".

Error Responses

Status Code When
404 SESSION_NOT_FOUND No session with this ID.

Example

curl https://gateway.chaoscha.in/v1/sessions/sess_abc123.../evidence

GET /v1/sessions/:id/viewer

Returns a self-contained HTML page for human inspection of a session: header (session_id, status, agent, studio, task_type, timestamps, workflow_id, data_hash link), evidence timeline (nodes sorted by timestamp with event_type badges, ROOT/TERMINAL markers, parent→child arrows), and footer (merkle_root, node count, roots, terminals). No API key required. Intended for browser use.

Path Parameters

Name Type Description
id string Session ID.

Response 200 OK

  • Content-Type: text/html
  • Body: Single HTML document (dark theme, monospace).

Error Responses

Status Code When
404 SESSION_NOT_FOUND No session with this ID.

Example

Open in a browser:

  • Local: http://localhost:3000/v1/sessions/<session_id>/viewer
  • Production: https://gateway.chaoscha.in/v1/sessions/<session_id>/viewer