Open API Reference

This chapter summarizes the currently available APIs, grouped by capability into seven categories: Auth, UserProfile, Local Assistant, Cloud Tasks, ACP Channel, Session Artifacts, and Redemption Code Redemption. Developers can first choose the category that matches their business goals, then complete integration based on each API's permission requirements, request parameters, and response structure.

• Auth API: Complete user authorization and exchange for access credentials.
• UserProfile API: Read the total credit quota and amount used for the currently authorized user.
• Local Assistant API: Query PC local assistant status, send messages, and query message history.
• Cloud Task API: Create and query cloud tasks, and obtain ACP connection information for the task.
• ACP Channel: Establish a real-time bidirectional communication channel for cloud tasks and exchange protocol messages.
• Session Artifacts: Query plans, tasks, media, summaries, and other artifacts produced by cloud sessions.
• Redemption Code Redemption API: Issue credits to the currently authorized user via redemption codes or vouchers.

Auth API

Overview

WorkBuddy Open Platform implements third-party application authorization based on the OAuth 2.1 authorization code flow. Developers guide users through authorization via the /authorize endpoint, then exchange the authorization code at the /token endpoint for access credentials (access_token) and refresh credentials (refresh_token). Subsequent Open API calls are authenticated with access_token.

This section includes two core endpoints:

• "Request User Authorization" — Guide the user to complete authorization in the browser
• "Exchange for Access Credentials" — Exchange an authorization code or refresh credential for an access_token

Request User Authorization

Guide the user to open the authorization page in the browser. After the user confirms, the platform callbacks with an Authorization Code.

Query Parameters

Request Example

GET /openapi/v2/authorize?response_type=code&client_id=app_7a3f2b1c&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=user.task.readable%20user.localassistant.readable&state=a1b2c3_random_xyz HTTP/1.1
Host: www.workbuddy.cn
Accept: text/html

Callback Response

After the user confirms authorization, the platform redirects to redirect_uri with the following parameters:

GET https://example.com/callback?code=auth_c0d3_xyz789&state=a1b2c3_random_xyz

Exchange for Access Token

Exchange the authorization code for an access_token.

Request Body

Request Example

POST /openapi/v2/token HTTP/1.1
Host: www.workbuddy.cn
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=auth_c0d3_xyz789&client_id=app_7a3f2b1c&client_secret=sk_live_abc123...&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback

Response Body

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "def50200a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p...",
  "scope": "user.task.readable user.localassistant.readable",
  "open_id":"op_9f8e7d6c5b4a"
}

Refresh Access Token

Use refresh_token to refresh the access_token.

Request Body

Request Example

POST /openapi/v2/token HTTP/1.1
Host: www.workbuddy.cn
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=refresh_token&refresh_token=wbjt_xxxxxxxxxxxxx&client_id=cb_xxxxxxxxxxxxx&client_secret=xxxxxxxxxxxxx

Response Body

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "user.profile.readable task.write",
  "open_id": "op_9f8e7d6c5b4a"
}

UserProfile API

Overview

The UserProfile API is used to query the total credit quota and amount used for the currently authorized user. The API supports personal users only. It does not distinguish subscription packs, top-up packs, or gift packs, and only counts resource packs whose status is "valid" or "used up".

Read Personal Credits

Request

GET /openapi/v2/credit HTTP/1.1
Host: www.workbuddy.cn
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "total_capacity_size": 3609,
  "total_capacity_used": 285
}

Response Body

Local Assistant API

Overview

The Local Assistant API is used for message interaction with the PC local assistant connected to WorkBuddy, including querying online status, sending messages, and querying message history.

Query Local Assistant Online Status

Query whether the current user's PC local assistant is online.

Request

GET /openapi/v2/localassistant HTTP/1.1
Host: www.workbuddy.cn
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 74

{"code":0,"msg":"success","request_id":"a1b2c3d4e5","data":{"online":true}}

Response data

Send Message to Local Assistant

Send a message to the PC local assistant to trigger the assistant to execute a task.

Request

POST /openapi/v2/localassistant/message HTTP/1.1
Host: www.workbuddy.cn
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Accept: application/json
Content-Length: 52

{"content":"帮我查一下今天的日程","msg_type":"text"}

Request body

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 87

{"code":0,"msg":"success","request_id":"a1b2c3d4e5","data":{"message_id":"msg-001"}}

Response data

Query Local Assistant Message History

Query the current user's local assistant message history, with support for pagination and incremental queries.

Request (pagination mode)

GET /openapi/v2/localassistant/message?limit=20&offset=0 HTTP/1.1
Host: www.workbuddy.cn
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

Request (incremental mode)

GET /openapi/v2/localassistant/message?message_id=msg-001 HTTP/1.1
Host: www.workbuddy.cn
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

Query Parameters

When message_id is provided, incremental mode is used; otherwise pagination mode is used.

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 396

{"code":0,"msg":"success","request_id":"a1b2c3d4e5","data":{"messages":[{"message_id":"msg-001","role":"user","content":["帮我查一下今天的日程"],"msg_type":"text","created_at":"2026-07-30T10:00:00Z","attachments":[],"metadata":{"msgType":"text"}},{"message_id":"msg-002","role":"assistant","content":["你今天有3个日程..."],"msg_type":"text","created_at":"2026-07-30T10:00:05Z","attachments":[],"metadata":{"msgType":"text"}}]}}

Response data

messages[] single message element

Cloud Task API

Overview

The Cloud Task API is used to create and query cloud tasks, and returns the ACP connection URL and auth token for establishing real-time communication with the cloud session.

Create Cloud Task

Create a cloud task. Supports interconnection with WorkBuddy mobile or mini-program sessions. Returns task_id, ACP link, and token.

Request

POST /openapi/v2/tasks HTTP/1.1
Host: www.workbuddy.cn
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "prompt": "帮我看下明天的天气如何",
  "name": "明天天气"
}

Request Body

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "task_id": "2076261663968759808",
  "status": "working",
  "name": "明天天气",
  "link": "https://acp.workbuddy.cn/sessions/2076261663968759808",
  "token": "sk-sandbox-xxxxxxxxxxxxxxxxxxxx",
  "expire_at": 1786087200,
  "sandboxLink": "https://sandbox.example.com/e2b/abc123",
  "sandboxDataLink": "https://sandbox-data.example.com/e2b/abc123"
}

Response Body

status field enum

Query Cloud Task List

Query the list of cloud tasks created by the current user, with pagination support. Returns basic task information and ACP Link; does not return ACP Token or its expiration time.

Request

GET /openapi/v2/tasks?page=1&size=20 HTTP/1.1
Host: www.workbuddy.cn
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

Query Parameters

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "tasks": [
    {
      "task_id": "2076261663968759808",
      "status": "working",
      "name": "明天天气",
      "link": "https://acp.workbuddy.cn/sessions/2076261663968759808",
      "created_at": "2026-08-04T10:30:00Z",
      "updated_at": "2026-08-04T10:35:00Z"
    },
    {
      "task_id": "2076261663968759809",
      "status": "completed",
      "name": "日程整理",
      "link": "https://acp.workbuddy.cn/sessions/2076261663968759809",
      "created_at": "2026-08-03T08:00:00Z",
      "updated_at": "2026-08-03T09:00:00Z"
    }
  ],
  "total": 2,
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 2
  }
}

Response Fields

Note: The list API does not return token or expire_at. To obtain a task's ACP Token, call GET /openapi/v2/tasks/{task_id}.

Query Cloud Task

Query task status and obtain a new ACP link/token. Responds with 200 OK. After creating a task, if the response temporarily lacks link or token, poll this API until they are populated.

Request

GET /openapi/v2/tasks/2076261663968759808 HTTP/1.1
Host: www.workbuddy.cn
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

Path Parameters

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "task_id": "2076261663968759808",
  "status": "working",
  "name": "明天天气",
  "link": "https://acp.workbuddy.cn/sessions/2076261663968759808",
  "token": "sk-sandbox-xxxxxxxxxxxxxxxxxxxx",
  "expire_at": 1786087200,
  "sandboxLink": "https://sandbox.example.com/e2b/abc123",
  "sandboxDataLink": "https://sandbox-data.example.com/e2b/abc123"
}

Response Body

status field enum

ACP Usage Notes

Start a Conversation

Use the ACP channel to start a conversation. After creating or querying a task to obtain link and token, use them to communicate with the cloud session. ACP (Agent Client Protocol) is based on SSE long connections + JSON-RPC 2.0 and uses a dual-channel model: one GET SSE long connection for receiving server pushes (streaming answers, notifications), and POST requests for sending JSON-RPC calls. Both are associated via the same connection identifier.

Connection and Authentication

1. Receive channel: GET {link}, with request headers Authorization: Bearer {token} and Accept: text/event-stream, to establish an SSE long connection for receiving server messages. The Acp-Connection-Id in the response headers is the identifier for this connection.
2. Send channel: POST {link}, with request headers Authorization: Bearer {token}, Content-Type: application/json, and the Acp-Connection-Id echoed to associate with the SSE connection above; Body is a JSON-RPC request. Call results (including streaming answers) are pushed back asynchronously via the SSE channel.
3. token: Used only for ACP channel authentication. Due to differences in the underlying Agent sandbox environment, token validity varies—typically 3 days, but it may also be much shorter. If the caller receives a 401 on an ACP request, use GET /tasks/{task_id} to obtain a new token.

Conversation Flow (JSON-RPC)

1. initialize: Negotiate protocol version and client capabilities; call once immediately after connecting.
2. session/load: Load the created session; pass the task_id returned when creating the task as params.sessionId.
3. session/prompt: Send a question; params.prompt is a ContentBlock array (each element contains type=text and a text field; see example below). For follow-ups, reuse the same sessionId and call again.

Complete call example (send in order after connecting; results and streaming answers are pushed back via the SSE channel):

// 1) initialize — 协商协议版本与客户端能力，建连后先调用一次
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": 1,
    "clientCapabilities": {
      "fs": { "readTextFile": false, "writeTextFile": false }
    }
  }
}

// 2) session/load — 加载已创建的会话，sessionId 传创建任务返回的 task_id
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/load",
  "params": {
    "sessionId": "2076261663968759808",
    "cwd": "/workspace",
    "mcpServers": []
  }
}

// 3) session/prompt — 发送提问，prompt 为 ContentBlock 数组；追问时复用同一 sessionId 再次调用
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "session/prompt",
  "params": {
    "sessionId": "2076261663968759808",
    "prompt": [{ "type": "text", "text": "帮我看下明天的天气如何" }]
  }
}

Receiving Server Messages

The server pushes two types of JSON-RPC messages via the SSE channel:

• Notification (no id): One-way push for streaming answers, status changes, extension events, etc. The client does not need to reply.
• Server-to-Client Request (with id): The client must return a response via the SSE-associated Acp-Connection-Id before timeout. Used for interactions that require user participation (tool permission confirmation, AskUserQuestion, etc.).

Task completion determination: The session/prompt response is the authoritative signal for "this round ended"; result.stopReason indicates the end reason (end_turn / max_tokens / max_turn_requests / refusal / cancelled).

Extension Method Notes

In addition to standard ACP methods, the server also pushes extension JSON-RPC notifications prefixed with _codebuddy.ai/ via the SSE channel to carry session assets not defined by the ACP standard protocol (such as artifacts, breakpoints, commands, etc.). These messages:

• Follow the JSON-RPC 2.0 specification (no id; no reply required)
• Methods unrecognized by the client can be safely ignored without affecting the standard protocol flow
• Are not defined in the official ACP protocol (agentclientprotocol.com); they are WorkBuddy cloud private extensions to ACP

Extension methods that integrators most need to pay attention to:

Artifact notification example:

{
  "jsonrpc": "2.0",
  "method": "_codebuddy.ai/artifact",
  "params": {
    "sessionId": "2076261663968759808",
    "event": "created",
    "artifact": {
      "type": "media",
      "uri": "agent:///artifacts/output.png",
      "mimeType": "image/png",
      "size": 102400
    }
  }
}

Three event values:

• created: New artifact added; artifact is the full object.
• updated: Artifact changed; artifact is the full object (full overwrite, not a diff).
• deleted: Artifact removed; artifact guarantees only the type and uri fields.

Clients should use artifact.uri as the primary key for local upsert / delete; receiving a duplicate created should be treated as equivalent to updated.

Artifact List API

The SSE channel pushes incremental events. To fetch all historical artifacts in a session at once (e.g. first-screen rendering, state recovery), use the REST API GET /api/session/artifacts. SSE and REST share the same data source and can be combined (REST for full load on first screen + SSE for subsequent increments).

sandbox_url is obtained by removing the trailing /acp path segment from the link field returned by the "Create Cloud Task" / "Query Cloud Task" APIs. For example, if link = "https://65225-xxx.ap-guangzhou.agentos-run.net/acp", then sandbox_url = "https://65225-xxx.ap-guangzhou.agentos-run.net".

The authentication credential task_ticket is the same one shared with the ACP channel. If task_ticket is expired, HTTP 401 is returned; call the "Query Cloud Task" API to obtain a new task_ticket and retry.

Query Parameters

Request Example

# 拉取当前会话的全部产物
curl -H "Authorization: Bearer {task_ticket}" \
     "{sandbox_url}/api/session/artifacts"

# 仅拉取媒体类产物，分页
curl -H "Authorization: Bearer {task_ticket}" \
     "{sandbox_url}/api/session/artifacts?type=media&limit=50&offset=0"

# 增量拉取（配合本地记录的 lastUpdatedAt）
curl -H "Authorization: Bearer {task_ticket}" \
     "{sandbox_url}/api/session/artifacts?startMs=1730000000000"

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 0,
  "msg": "success",
  "data": {
    "sessionId": "2076261663968759808",
    "artifacts": [
      {
        "sessionId": "2076261663968759808",
        "event": "created",
        "artifact": { /* Artifact 对象，见下方字段说明 */ },
        "md5": "3f2a...",
        "url": "https://.../artifacts/output.png"
      }
    ],
    "pagination": {
      "total": 123,
      "returned": 50,
      "limit": 50,
      "offset": 0,
      "hasMore": true
    },
    "filter": { "type": "media", "startMs": 0, "endMs": 0 }
  }
}

Response Fields (top level)

Entry Fields (data.artifacts[])

Artifact Common Fields

Artifact Type-Specific Fields

type = plan (plan document, Markdown):

type = tasks (task list):

type = media (media file):

Downloading media files: Prefer the url field at the Entry level; if not provided, replace agent:/// in uri with {sandbox_url}/ and request (reuse the same task_ticket for authentication).

type = overview (task summary, Markdown):

Error Responses

Error response body format:

{
  "code": 1,
  "msg": "invalid type: xxx (allowed: plan|tasks|media|overview)"
}

Usage recommendations

• First-screen rendering: Call the REST API once when entering a session to fetch all artifacts, and build a local index by artifact.uri.
• Incremental updates: Subscribe to SSE _codebuddy.ai/artifact notifications and upsert / delete in the local index by event.
• Session recovery: The REST first-screen + SSE incremental combination is naturally idempotent; no special "recovery branch" is needed—simply overwrite by the same uri.

Redemption Code Redemption API

Overview

Redeem a redemption code or voucher to issue credits to the currently authorized user. The API supports single-code mode and dual-code mode.

Redeem Redemption Code

Request (Scenario A: redemption code)

POST /openapi/v2/redemptions HTTP/1.1
Host: www.workbuddy.cn
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Accept: application/json
Content-Length: 78

{"code":"CODE-OPER-8888","request_id":"550e8400-e29b-41d4-a716-446655440000"}

Request (Scenario B: pickup voucher)

POST /openapi/v2/redemptions HTTP/1.1
Host: www.workbuddy.cn
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Accept: application/json
Content-Length: 102

{"gift_key":"GK-000001","gift_code":"CODE-XXX","request_id":"550e8400-e29b-41d4-a716-446655440000"}

Request body

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 158

{"status":"success","flow_no":"flow-2026072912345","credits":100,"open_id":"pairwise-open-id-xxx"}

Response Fields

Return codes

Return Code Specification

All Open APIs follow a unified return code specification. When an API call fails, use the HTTP status code, business code, and troubleshooting suggestions to locate the issue.