跳到主要内容

API Reference

POST /api/execute​

This is the current public C2AI2X ingress route.

Route contract​

  • route id: brain.execute
  • auth: admin_or_api_key
  • security: bearerAuth
  • surface: gateway
  • stability: phase1_gateway
  • current public phase: phase 1

Request body​

Schema: current zhen-platform-core execute request body as defined in spec/openapi.yaml

Key fields:

  • domain: string
  • execution_mode: "sync" | "async"
  • required_scopes: string[]
  • text?: string
  • structured_input?: Record<string, unknown>
  • key_id?: string
    • required on the admin bearer path
    • not required on the api_key bearer path because the platform derives it from the bearer
  • attachments?: { attachment_id: string; kind: string; url?: string; metadata?: Record<string, unknown> }[]
  • request_id?: string
  • trace_id?: string
  • idempotency_key?: string
  • project_id?: string
  • user_id?: string
  • session_id?: string
  • exact_bridge?: ExactBridgeMetadata

Current contract note:

  • neutral protocol objects such as Demand, Envelope, and AuthorizationGrant belong to the standard layer in zhen-protocol-c2ai2x
  • the current executable HTTP contract does not freeze those objects as top-level request fields on POST /api/execute
  • when needed, callers can carry protocol-layer objects inside structured_input for platform-side translation and audit preservation

Response 200​

Synchronous success returns a completed execution envelope:

{
  "output": {
    "request_id": "req_...",
    "trace_id": "trace_...",
    "status": "completed"
  },
  "usage_applications": [],
  "exact_bridge": {
    "contract_id": "...",
    "escrow_id": "...",
    "org_id": "...",
    "organization_id": "...",
    "workspace_id": "...",
    "audit_id": "...",
    "source_layer": "platform-core",
    "source_record": "canonical_audit"
  }
}

Response 202​

Async acceptance returns 202 Accepted:

{
  "accepted": {
    "status": "accepted",
    "workflow_id": "wf_...",
    "stream_url": "/api/workflows/wf_.../stream",
    "query_url": "/api/workflows/wf_...",
    "cancel_url": "/api/workflows/wf_.../cancel",
    "message": "Workflow accepted. Connect to stream_url for real-time progress."
  }
}

Translation semantics​

The platform currently performs these core translations:

  • text is the direct plain-text execution path
  • structured_input is the carrier for richer structured context
  • neutral Demand, Envelope, and AuthorizationGrant objects may be embedded in structured_input when an integrator wants to preserve protocol-layer meaning
  • attachment objects in the current live contract support attachment_id, kind, optional url, and optional metadata
  • exact_bridge is optional and only used when the execution must stay linked to platform-side business truth

Boundary reminder​

This route is the public protocol ingress at zhen-platform-core. It is not a direct public zhen-brain-core API.