跳到主要内容

C2AI2X Quickstart

The fastest integration path is:

  1. Get a platform-issued Bearer credential
  2. Build the minimum executable platform request
  3. Call POST /api/execute
  4. Handle either 200 or 202

1. Auth​

The live public route uses platform admission with a Bearer credential.

  • route auth contract: admin_or_api_key
  • OpenAPI security: bearerAuth

That means the external caller still sends Authorization: Bearer <token>, and zhen-platform-core decides whether the credential is valid for this ingress.

2. Minimum request​

The current phase 1 executable subset requires:

  • domain
  • required_scopes
  • execution_mode
  • text or structured_input
  • key_id only when the bearer actor is admin
{
  "domain": "zhenins",
  "execution_mode": "sync",
  "required_scopes": [],
  "text": "I need an insurance consultation."
}

Add these as soon as you move beyond the first successful request:

  • required_scopes
  • attachments
  • request_id
  • trace_id
  • idempotency_key
  • project_id
  • user_id
  • session_id
  • exact_bridge

If you need to preserve neutral protocol objects such as Demand, Envelope, or AuthorizationGrant, carry them inside structured_input for platform translation and audit. They are not the frozen top-level HTTP contract of the current POST /api/execute route.

4. Sync example​

curl -X POST "$BASE_URL/api/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "zhenins",
    "execution_mode": "sync",
    "required_scopes": [],
    "text": "I need an insurance consultation."
  }'

Success returns 200:

{
  "output": {
    "request_id": "req_...",
    "trace_id": "trace_...",
    "status": "completed"
  },
  "usage_applications": []
}

5. Async example​

When execution_mode = "async", success returns 202:

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

Consume the returned workflow URLs from zhen-platform-core. Do not call zhen-brain-core directly.

Next reads​