API And Events

AgentHub public contracts are split into REST APIs, WebSocket events, runtime adapter events, and IM integration events. This page describes the intended boundaries; complete OpenAPI specs, event schemas, and SDK packages are still in development.

Contract Layers

The owning source for protocol details is the AgentHub repository api/ directory. This public site keeps the reader-facing map: what each layer is for, which side owns it, and what should not cross the boundary.

Stability Matrix

Last public verification date: 2026-06-09. If the AgentHub repository OpenAPI or event schema conflicts with this page, treat the owning repository schema as authoritative and update this page in the same pass.

Hub API

Hub API owns collaboration and permission boundaries. Typical resources include:

• sessions: user sessions, Hub sessions, and low-risk personalization state.
• projects: team projects, workspace links, visibility, and membership.
• devices: Desktop / Edge device registration, presence, and routing targets.
• tasks: work requests from Web, Desktop, or IM.
• runs: agent execution instances and run state.
• audit: important actions, approvals, failures, and authorization decisions.

Hub API should not expose model API keys, and Web clients must not bypass Hub to operate local workspaces directly.

Expected Hub API groups:

Public examples should use placeholder hosts and tokens. Do not copy production admin keys, JWTs, or private callback payloads into docs.

The minimum request shape looks like this. Paths and fields remain in preview until the public OpenAPI is stable:

GET /client/sessions HTTP/1.1
Host: hub.example.invalid
Authorization: Bearer <agenthub_session_token>
Accept: application/json

{
  "items": [
    {
      "id": "session_123",
      "projectId": "project_123",
      "title": "Local review",
      "state": "active",
      "updatedAt": "2026-06-09T00:00:00Z"
    }
  ],
  "nextCursor": null
}

Edge API

Edge API owns the local execution boundary. Typical capabilities include:

• list and select workspaces;
• start, cancel, and inspect runs;
• read run events, artifacts, diffs, and previews;
• manage runtime adapter presets;
• perform local health checks.

Edge sits close to the filesystem and process boundary, so it should default to conservative behavior: least privilege, workspace allowlist, explicit approval, and auditable events.

Expected Local Edge groups:

Browser WebSocket clients cannot reliably set custom headers, so a local Edge token may be passed during WebSocket upgrade using a query parameter. This protects only the loopback Edge process; Hub/Remote/Cloud routing still requires Hub-issued sessions, target authorization, and audit.

Preview example for creating a Local Edge run:

POST /v1/runs HTTP/1.1
Host: 127.0.0.1:3210
Content-Type: application/json
Authorization: Bearer <local_edge_token>

{
  "workspace": "workspace_123",
  "agentId": "codex-local",
  "input": {
    "text": "Review README and suggest one documentation improvement."
  },
  "mode": "read_only"
}

Example WebSocket event stream:

ws://127.0.0.1:3210/v1/events?runId=run_123&token=<local_edge_token>

WebSocket Events

WebSocket events stream execution progress to Desktop/Web:

Fields should remain versionable. Clients must not depend on undeclared internal fields.

Event Vocabulary

Use this vocabulary across API docs, runtime adapters, Desktop/Web rendering, search terms, and release notes. Do not mix bare names such as message.delta with run-scoped names.

Event Envelope

Every event should be easy for Desktop/Web to render and easy for audit code to store. Keep a stable envelope and version the payload:

Recommended client behavior:

• ignore unknown event types while preserving them in logs;
• deduplicate by id or seq;
• render partial events as progressive state, not final truth;
• keep raw event details out of public screenshots when they contain paths, prompts, or model output that should stay private.

Example event:

{
  "id": "evt_001",
  "seq": 1,
  "type": "run.tool.call",
  "runId": "run_123",
  "sessionId": "session_123",
  "agentId": "codex-local",
  "createdAt": "2026-06-09T00:00:00Z",
  "payload": {
    "tool": "read_file",
    "label": "Read README",
    "status": "started"
  }
}

Runtime Adapter Events

Runtime adapters normalize CLI/runtime output. Claude Code NDJSON, Codex JSONL/event streams, and OpenCode JSON events should all become AgentHub events.

An adapter should at least express:

• run start, completion, and failure;
• model messages and deltas;
• tool calls and tool results;
• file changes, diffs, and artifacts;
• states that require approval or additional input.

Runtime adapter events should use the run-scoped vocabulary above when describing runtime output: text deltas, tool calls, tool results, file changes, permission requests, session initialization, and final results. Adapter-specific raw messages may be attached for debugging only when they do not expose secrets.

IM Integration Events

Feishu/Lark integration events are handled by Integration Gateway and converted into Hub tasks or actions. Current focus:

• im.message.receive_v1: direct message or group @mention to the bot.
• card.action.trigger: interactive card action callback.
• TokenDance ID binding state updates.

These events must be acknowledged quickly, slow work must be queued asynchronously, and secrets or full workspace context must not be placed in card payloads.

Error Shape

REST APIs should return a predictable error shape so Web/Desktop can show recoverable failures without parsing logs:

Use specific codes for expected states: invalid agent id, unauthorized target, workspace outside allowlist, permission denied, runtime unavailable, timeout, cancellation, and schema validation failure.

Recommended error codes:

Authorization Matrix

The contract should make the authorization boundary explicit before a handler starts work.

Do not reuse TokenDance API keys for these product actions. TokenDance API keys authenticate model API calls through TokenDance Gateway; AgentHub product actions require TokenDance ID and Hub/Edge authorization.

Pagination And Idempotency

Hub APIs that list sessions, projects, tasks, runs, audit events, or messages should support cursor pagination. Public docs should not promise offset pagination unless the owning OpenAPI says so.

Recommended list shape:

{
  "items": [],
  "nextCursor": null,
  "requestId": "req_123"
}

Write endpoints that can be retried by Web, Desktop, Hub, or Integration Gateway should accept an idempotency key, or derive one from the upstream event id. This matters most for IM card actions, task creation, run creation, approval actions, and artifact publication.

Compatibility Checklist

Before treating an API or event group as stable, verify:

1. English and Chinese docs describe the same status and boundary.
2. OpenAPI or event schema exists in the owning AgentHub repository.
3. Desktop/Web render unknown fields safely.
4. Error codes cover unauthorized target, workspace allowlist, runtime unavailable, timeout, cancellation, and schema validation.
5. Request and event examples use placeholder hosts, placeholder tokens, and redacted paths.
6. Search index, sidebar TOC, llms.txt, sitemap, FAQ, and changelog mention the contract where relevant.

Security Boundary

• TokenDance ID authenticates the user; Hub issues and validates AgentHub product sessions.
• TokenDance API keys authenticate model API calls. They are not AgentHub browser login credentials.
• Web is Hub-only and must not call Local Edge directly.
• Desktop may call Local Edge on loopback for local execution.
• Edge may touch local files only inside allowlisted workspaces.
• Feishu/Lark events must resolve account binding through TokenDance ID before becoming Hub tasks.

Versioning

• REST APIs should be governed by OpenAPI.
• WebSocket events should have versionable schemas.
• Runtime adapter contract changes must be synchronized with Desktop/Web rendering and audit logic.
• Until a public SDK package is released, examples in docs are architectural guidance and do not promise stable import paths.

Schema Sources

Use this page as the public reading guide. For implementation work, consult these source-of-truth files in the AgentHub repository: