REST API
+REST API
The Cowork server exposes a versioned REST API at /api/v1.
- All endpoints return JSON. The interactive docs are available at
- /docs when the server is running.
+ All endpoints return JSON.
REST API
Responses
Stream AI responses from the agent. Compatible with the OpenAI Responses API shape.
+Response object
+{
+ "id": "resp_abc123",
+ "conversation_id": "conv_xyz",
+ "input": "Summarise last week's sales data",
+ "output": [{ "type": "text", "text": "Here is the summary..." }],
+ "status": "completed", // "in_progress" | "completed" | "failed"
+ "model": "claude-opus-4-8",
+ "usage": { "input_tokens": 120, "output_tokens": 340 },
+ "created_at": "2026-06-11T10:00:00Z"
+}
+ Responses
Create a streaming responseSends a message and streams back the agent's response as server-sent events.
+Body
+| conversation_id | string | required | ID of the conversation to append the response to. |
| input | string | required | User message text. |
| stream | boolean | optional | Default true. Return server-sent events. Set to false for a single JSON response. |
| model | string | optional | Override the agent model for this turn. Defaults to the project setting. |
| skill_ids | string[] | optional | Skill IDs to activate for this turn. |
curl -X POST http://localhost:26866/api/v1/responses \ -H "Content-Type: application/json" \ - -d '{"conversation_id": "...", "input": "Summarise last week'\''s sales data"}'+ -d '{"conversation_id":"conv_xyz","input":"Summarise last week'\''s sales data","stream":true}'
Responses
/responses/in-flight-list List active streamsQuery parameters
+| conversation_id | string | optional | Filter to a specific conversation. |
Query parameters
+| conversation_id | string | required | Conversation whose active stream to retrieve. |
Responses
Conversations
-Manage conversation threads. Each conversation holds an ordered list of messages.
+Manage conversation threads. Each conversation holds an ordered list of messages. Conversations and Tasks are the same concept — every task is a conversation with a goal and an assigned agent. The API uses both terms interchangeably.
+ +Conversation object
+{
+ "id": "conv_abc123",
+ "project_id": "proj_xyz", // null if not project-scoped
+ "title": "Q2 analysis",
+ "goal": "Analyse Q2 revenue by region", // task prompt, optional
+ "status": "active", // "active" | "archived"
+ "created_at": "2026-06-11T10:00:00Z",
+ "updated_at": "2026-06-11T10:04:12Z"
+}
+ Conversations
/conversations List conversationsQuery parameters
+| project_id | string | optional | Filter to a specific project. |
| status | string | optional | active or archived. Returns all if omitted. |
| limit | integer | optional | Max results to return. Default 50, max 200. |
| offset | integer | optional | Pagination offset. Default 0. |
Conversations
Create a conversationBody
+| project_id | string | optional | Attach to a project. |
| title | string | optional | Human-readable name. Auto-generated from the first message if omitted. |
| goal | string | optional | Task prompt or goal that frames the conversation for the agent. |
curl -X POST http://localhost:26866/api/v1/conversations \ -H "Content-Type: application/json" \ - -d '{"project_id": "...", "title": "Q2 analysis"}'+ -d '{"project_id":"proj_xyz","title":"Q2 analysis","goal":"Analyse Q2 revenue by region"}'
Path parameters
+| id | string | required | Conversation ID. |
Body
+| title | string | optional | New title. |
| goal | string | optional | Updated task goal. |
| status | string | optional | active or archived. |
Returns an ordered array of message items. Each item has role (user or assistant), content, and created_at.
Query parameters
+| limit | integer | optional | Default 100. |
| before | string | optional | Return items before this item ID (cursor pagination). |
Conversations
Projects
Projects are workspaces that group conversations, files, and artifacts.
+Project object
+{
+ "id": "proj_abc123",
+ "name": "Sales Automation",
+ "description": "Weekly reporting flows",
+ "connector_ids": ["conn_001", "conn_002"],
+ "skill_ids": ["skill_abc"],
+ "created_at": "2026-06-11T10:00:00Z",
+ "updated_at": "2026-06-11T10:00:00Z"
+}
+ Query parameters
+| limit | integer | optional | Default 50. |
| offset | integer | optional | Default 0. |
Projects
Create a projectBody
+| name | string | required | Display name for the project. |
| description | string | optional | Short description shown in the UI. |
| connector_ids | string[] | optional | Data source connections available within this project. |
| skill_ids | string[] | optional | Global skills to activate for all conversations in this project. |
curl -X POST http://localhost:26866/api/v1/projects \ -H "Content-Type: application/json" \ - -d '{"name": "Sales Automation", "description": "Weekly reporting flows"}'+ -d '{"name":"Sales Automation","description":"Weekly reporting flows","connector_ids":["conn_001"]}'
Body
+| name | string | optional | |
| description | string | optional | |
| connector_ids | string[] | optional | Replaces the current list. |
| skill_ids | string[] | optional | Replaces the current list. |
Projects
Artifacts
-Artifacts are the outputs the agent creates — apps, reports, dashboards, documents. Each artifact belongs to a project.
+Artifacts are mini apps — web apps, dashboards, reports, and documents generated by the agent and hosted within a project. Each artifact belongs to a project.
+ +Artifact object
+{
+ "id": "art_abc123",
+ "project_id": "proj_xyz",
+ "title": "Sales Dashboard",
+ "type": "app", // "app" | "report" | "doc" | "dashboard"
+ "path": "sales_dashboard/index.html", // relative path within project
+ "created_at": "2026-06-11T10:00:00Z",
+ "updated_at": "2026-06-11T10:00:00Z"
+}
+ Query parameters
+| project_id | string | optional | Filter to a project. |
| type | string | optional | app, report, doc, or dashboard. |
| limit | integer | optional | Default 50. |
Query parameters
+| path | string | required | Relative artifact path, e.g. sales_dashboard/index.html. |
| project_id | string | required | Project that owns the artifact. |
Body
+| artifact_id | string | required | Artifact to open in the Electron window. |
Path parameters
+| project_id | string | required | Project ID. |
| path | string | required | File path within the artifact, e.g. index.html or assets/chart.js. |
Artifacts
Schedules
Run tasks on a cron schedule. Schedules belong to a project and trigger a conversation or workflow automatically.
+Schedule object
+{
+ "id": "sched_abc123",
+ "project_id": "proj_xyz",
+ "cron": "0 9 * * 1", // standard 5-field cron expression
+ "timezone": "America/New_York",
+ "prompt": "Generate weekly sales digest",
+ "conversation_id": null, // null = create new conversation each run
+ "status": "active", // "active" | "paused"
+ "last_run_at": "2026-06-09T09:00:00Z",
+ "next_run_at": "2026-06-16T09:00:00Z",
+ "created_at": "2026-06-01T00:00:00Z"
+}
+ Query parameters
+| project_id | string | optional | Filter to a project. |
| status | string | optional | active or paused. |
Schedules
Create a scheduleBody
+| project_id | string | required | Project this schedule belongs to. |
| cron | string | required | Standard 5-field cron expression, e.g. "0 9 * * 1" = every Monday at 09:00. |
| prompt | string | required | Task the agent runs at each scheduled time. |
| timezone | string | optional | IANA timezone. Default UTC. |
| conversation_id | string | optional | Append each run to an existing conversation. If omitted, a new conversation is created per run. |
curl -X POST http://localhost:26866/api/v1/schedules \ -H "Content-Type: application/json" \ - -d '{"project_id": "...", "cron": "0 9 * * 1", "prompt": "Generate weekly sales digest"}'+ -d '{"project_id":"proj_xyz","cron":"0 9 * * 1","prompt":"Generate weekly sales digest","timezone":"America/New_York"}'
Body
+| cron | string | optional | New cron expression. |
| prompt | string | optional | Updated task prompt. |
| timezone | string | optional | New timezone. |
| status | string | optional | active or paused. |
Schedules
Files
-Upload and manage files that the agent can read, search, and reference during conversations.
+Upload and manage files that the agent can read, search, and reference. Files can be attached to a project or to individual conversations.
+ +File object
+{
+ "id": "file_abc123",
+ "name": "Q2-report.pdf",
+ "mime_type": "application/pdf",
+ "size": 204800, // bytes
+ "project_id": "proj_xyz", // null if conversation-scoped only
+ "conversation_id": null, // null if project-scoped only
+ "created_at": "2026-06-11T10:00:00Z"
+}
+ Query parameters
+| project_id | string | optional | Filter to a project. |
| conversation_id | string | optional | Filter to a conversation. |
Multipart form-data upload.
Form fields
+| file | file | required | The file binary. Accepted: PDF, DOCX, XLSX, CSV, TXT, PNG, JPG, and more. |
| project_id | string | optional | Attach to a project. |
| conversation_id | string | optional | Attach to a conversation. Can be set alongside project_id. |
curl -X POST http://localhost:26866/api/v1/files \ + -F "file=@Q2-report.pdf" \ + -F "project_id=proj_xyz"+
Files
Connectors
-Integrate external data sources. Connectors are defined by specs and instantiated as connections with encrypted credentials.
+Integrate external data sources. Connectors exist independently of any project but can be referenced inside any project. They are defined by specs (the connector type, e.g. PostgreSQL, Snowflake, Google Sheets) and instantiated as connections with encrypted credentials. Credentials are write-only — never returned after creation.
+ +ConnectorSpec object
+{
+ "id": "postgres",
+ "name": "PostgreSQL",
+ "description": "Connect to any PostgreSQL-compatible database.",
+ "auth_type": "credentials", // "credentials" | "oauth2"
+ "fields": [ // credential fields required at connection time
+ { "key": "host", "label": "Host", "secret": false },
+ { "key": "port", "label": "Port", "secret": false },
+ { "key": "database", "label": "Database", "secret": false },
+ { "key": "user", "label": "User", "secret": false },
+ { "key": "password", "label": "Password", "secret": true }
+ ]
+}
+ Connection object
+{
+ "id": "conn_abc123",
+ "spec_id": "postgres", // which ConnectorSpec this uses
+ "name": "prod-db",
+ "status": "connected", // "connected" | "error" | "pending"
+ "created_at": "2026-06-11T10:00:00Z"
+ // credentials are never returned
+}
+ Connectors
/connectors/specs List available connector specscurl "http://localhost:26866/api/v1/connectors/specs"+
Query parameters
+| spec_id | string | optional | Filter by connector type (e.g. postgres). |
Body
+| spec_id | string | required | The connector spec to use (e.g. "postgres"). |
| name | string | required | Human-readable label for this connection. |
| credentials | object | required | Key-value map of credential fields defined by the spec. Secret fields are encrypted at rest and never returned. |
curl -X POST "http://localhost:26866/api/v1/connectors/connections" \ + -H "Content-Type: application/json" \ + -d '{ + "spec_id": "postgres", + "name": "prod-db", + "credentials": { + "host": "db.example.com", + "port": 5432, + "database": "analytics", + "user": "reader", + "password": "s3cr3t" + } + }'+
Returns a redirect URL. Send the user's browser there; after authorization the platform receives the callback and stores the token automatically.
+Path parameter
+| spec | string | required | The connector spec ID (e.g. google-sheets, notion). |
Memories
+Persistent facts and context the agent retains across conversations. Memories can be global (shared across all projects and conversations) or project-scoped — omit project_id to create a global memory. The agent automatically surfaces relevant memories as context at the start of each conversation.
Memory object
+{
+ "id": "mem_abc123",
+ "content": "Prefers executive summaries under 200 words.",
+ "project_id": null, // null = global; string = project-scoped
+ "source": "user", // "user" | "agent" — who created it
+ "created_at": "2026-06-11T10:00:00Z",
+ "updated_at": "2026-06-11T10:00:00Z"
+}
+ Query parameters
+| project_id | string | optional | Return memories scoped to this project. Omit to return global memories. |
| source | string | optional | Filter by who created it: user or agent. |
curl "http://localhost:26866/api/v1/memories" # global +curl "http://localhost:26866/api/v1/memories?project_id=..." # project-scoped+
Body
+| content | string | required | The fact or preference to remember. Plain text. |
| project_id | string | optional | Scope to a project. Omit for a global memory. |
curl -X POST "http://localhost:26866/api/v1/memories" \ + -H "Content-Type: application/json" \ + -d '{"content": "Always use Q3 targets as the baseline.", "project_id": "proj_xyz"}'+
Body
+| content | string | optional | Updated text for the memory. |
Skills
+Reusable capabilities available globally across all projects — custom instructions, tools, or prompt templates the agent can invoke. Skills extend what the agent knows how to do without re-explaining it each time. Like Connectors, they exist independently of any single project.
+ +Skill object
+{
+ "id": "skill_abc123",
+ "name": "weekly-report",
+ "description": "Generates a weekly performance report from connected data sources.",
+ "instructions": "Always include a one-paragraph executive summary first. Use bullet points for metrics...",
+ "tools": [ // external tool integrations this skill may invoke
+ "sql_query",
+ "send_email"
+ ],
+ "created_at": "2026-06-11T10:00:00Z",
+ "updated_at": "2026-06-11T10:00:00Z"
+}
+ curl "http://localhost:26866/api/v1/skills"+
Body
+| name | string | required | Kebab-case identifier. Used to invoke the skill from a conversation. |
| description | string | required | Short summary of what this skill does. Shown in the UI and used by the agent to decide whether to invoke it. |
| instructions | string | optional | Detailed prompt injected whenever this skill is active. Explains how to carry out the task, preferred format, constraints, etc. |
| tools | string[] | optional | List of tool identifiers the agent may call when running this skill (e.g. "sql_query", "send_email"). |
curl -X POST "http://localhost:26866/api/v1/skills" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "weekly-report", + "description": "Generates a weekly performance report.", + "instructions": "Always start with an executive summary. Limit to 3 charts.", + "tools": ["sql_query", "send_email"] + }'+
Body
+| name | string | optional | New identifier. |
| description | string | optional | Updated summary. |
| instructions | string | optional | Revised prompt instructions. |
| tools | string[] | optional | Replace the full list of allowed tools. |
Scratchpads
+Notebook-style workspaces scoped to a conversation. A scratchpad is made up of ordered cells — the agent writes to cells as it reasons, drafts, and executes code. Each cell has a type (markdown, code, or output) and tracks its own execution state. Scratchpads persist for the lifetime of the conversation and can be promoted to an Artifact.
Scratchpad object
+{
+ "id": "sp_abc123",
+ "conversation_id": "conv_xyz",
+ "title": "Sales analysis draft",
+ "cells": [ /* ordered array of Cell objects */ ],
+ "saved": false, // true once promoted / pinned
+ "created_at": "2026-06-11T10:00:00Z",
+ "updated_at": "2026-06-11T10:04:12Z"
+}
+ Cell object
+{
+ "id": "cell_001",
+ "type": "code", // "markdown" | "code" | "output"
+ "content": "df.describe()",
+ "language": "python", // present when type = "code"
+ "status": "success", // "pending" | "running" | "success" | "error"
+ "outputs": [ // present when type = "output"
+ {
+ "mime": "text/plain",
+ "data": "count 12.0\nmean 4.2\n..."
+ },
+ {
+ "mime": "image/png",
+ "data": "data:image/png;base64,..."
+ }
+ ],
+ "error": null, // error message when status = "error"
+ "index": 0 // display order within the scratchpad
+}
+
+ type — markdown cells are prose written by the agent; code cells are executable snippets; output cells are the results attached to the preceding code cell (stdout, images, tables).
+ status — only relevant on code cells. pending means queued, running means currently executing, success/error are terminal states.
+ outputs — multi-modal: a single code cell can produce several output objects with different MIME types (plain text, HTML, PNG charts, JSON).
+
curl "http://localhost:26866/api/v1/scratchpads?conversation_id=..."+
curl -X POST "http://localhost:26866/api/v1/scratchpads" \ + -H "Content-Type: application/json" \ + -d '{"conversation_id":"...","title":"Sales analysis draft","cells":[]}'+
curl -X PATCH "http://localhost:26866/api/v1/scratchpads/{scratchpad_id}" \ + -H "Content-Type: application/json" \ + -d '{"title":"Final analysis","saved":true}'+
Cells
+Cells are managed individually so the agent can append, edit, or re-run a single cell without replacing the whole scratchpad.
+ +curl -X POST "http://localhost:26866/api/v1/scratchpads/{scratchpad_id}/cells" \ + -H "Content-Type: application/json" \ + -d '{"type":"code","language":"python","content":"df.head()"}'+
curl -X PATCH "http://localhost:26866/api/v1/scratchpads/{scratchpad_id}/cells/{cell_id}" \ + -H "Content-Type: application/json" \ + -d '{"content":"df.tail(10)","index":2}'+
Runs the cell and streams output back as server-sent events. Each event carries a partial output object. Terminal event has status: "success" or status: "error".
curl -X POST "http://localhost:26866/api/v1/scratchpads/{scratchpad_id}/cells/{cell_id}/run"+
Search
-Full-text and semantic search across conversations, files, and memory.
+Full-text and semantic search across conversations, artifacts, files, and memories. Returns ranked results with the matching resource type and a short excerpt.
+ +SearchResult object
+{
+ "type": "conversation", // "conversation" | "artifact" | "file" | "memory"
+ "id": "conv_abc123",
+ "title": "Sales forecast Q3",
+ "excerpt": "...the Q3 sales forecast shows a 12% increase over...",
+ "score": 0.93, // relevance score 0–1
+ "project_id": "proj_xyz" // null for global results
+}
+ Search
Search across the workspaceQuery parameters
+| q | string | required | The search query. Supports natural language and keyword matching. |
| project_id | string | optional | Limit results to a single project. |
| types | string[] | optional | Comma-separated list of resource types to include: conversation, artifact, file, memory. Defaults to all. |
| limit | integer | optional | Maximum results to return. Defaults to 20, max 100. |
curl "http://localhost:26866/api/v1/search?q=sales+forecast&project_id=..."+
curl "http://localhost:26866/api/v1/search?q=sales+forecast&project_id=proj_xyz&types=conversation,file&limit=10"+
Response
+{
+ "results": [
+ {
+ "type": "conversation",
+ "id": "conv_abc123",
+ "title": "Sales forecast Q3",
+ "excerpt": "...the Q3 sales forecast shows a 12% increase over...",
+ "score": 0.93,
+ "project_id": "proj_xyz"
+ }
+ ],
+ "total": 1
+}