Skip to main content
Everything a person does in a workspace can also be done from code, under /v1/workspaces of the public API or with devic workspaces (alias devic ws) in the CLI. The same permissions apply. Membership and roles are checked exactly as in the app.

Who a request acts as

Workspaces belong to people, so the first thing each request settles is who it acts as.
  • Acting for a person never adds permissions. An admin key acting for a consumer user can only do what that consumer can do in the app.
  • The account integration has no person behind it.
    • It sees the account’s shared workspaces only, never personal workspaces or private conversations.
    • It acts as a workspace manager, never as an owner.
    • Its messages are signed API.
  • Tenant-session tokens are rejected. They identify your customers, not members of your account.
Every message written this way records where it came from in origin: channel (api, cli or sdk) and the credential. The apps show it as a “via API / CLI / SDK” tag. The server sets it; a request body cannot.

Find the work

GET /v1/workspaces/threads covers every workspace you can see, or one with workspaceId:
  • search ignores case and accents, and every word must appear.
  • unread=true keeps threads with messages from others since your last read, or that were marked unread.
  • Results come newest activity first, paginated with offset and limit.
  • Each row carries unreadCount, unreadMentionCount, waitingForMe (a question or an approval waiting for you) and activeRunCount.

Read a thread

  • Messages are paged by seq, at most 200 per page.
  • Each page also returns the runs answering its messages, plus every run still in progress.
  • Reading never marks a thread read. Use POST …/read for that.

Write, and wait for the assistant

  • Asking an assistant: set directedAssistantId, mention it, or reply to one of its messages. The response lists the runs the message started.
  • Retries: clientMessageId makes them safe. The same id and body return the same message.
  • @everybody: add { "kind": "everyone", "id": "everyone", "label": "everybody" } to mentions and @everybody to the text (devic ws send … --everybody). It notifies everyone who can read the thread and never asks an assistant. Not for guests from another account; once every 10 minutes per author and thread (429 EVERYONE_MENTION_COOLDOWN, the message is not posted).
  • --wait: the CLI follows the runs until they finish or wait for you.

Direct messages

  • Private conversations are account-wide and live in one hidden space of the account. Use its workspaceId with the usual thread endpoints to read, write, mark read or download files. It is null until the first conversation.
  • Opening a conversation with someone you already talk to returns the same one.
  • They need a person: the account integration (an API key without X-Devic-User) gets 403 DIRECT_MESSAGES_REQUIRE_USER.
  • GET /v1/workspaces/threads?kind=direct lists them among the rest.

When the assistant waits for you

A run in waiting_input asked a question. A run in waiting_approval wants to use a tool that needs approval.
Through the API, use POST …/invocations/{runId}/{action}:
  • answer: { revision, inputId, response: { answers } }, or skipped: true to skip the questions.
  • approve: { revision, actionId }, where actionId is the run’s requestedAction.id.
  • cancel and retry take the same route.
A stale revision returns 409: read the thread again and retry. The CLI fills in revision, inputId and actionId for you.

Files and documents

The download is the original file, with its name in Content-Disposition.

Configure a workspace

Settings, members, assistants, knowledge and skills, rules, core memory and automations are all available:
Each needs the same role as in the app. Changes that carry a revision (rules, resources, members, assistants) refuse a stale one with 409.

Build an automation

An automation reacts to an app event, runs on a schedule or runs on demand, and posts its results in a workspace. In the app, the Automations assistant designs it with you. Through the API and the CLI you compose it yourself, with the same information and the same validation:
1

See what it can use

2

Connect a missing app

The response carries the provider’s authorization link. The person opens it and accepts the consent screen; the account is connected only then. A shared workspace needs an account connected for everyone (--scope workspace).
3

Choose the event or the schedule

4

Grant tools and find the destination threads

5

Save the draft

The plan is validated before it is saved: accounts, tools, trigger configuration and destination. Saving never activates it.
6

Activate

Activation is the approval of that draft version, with the model that runs it: the included one, or a provider and model with your own key.
The plan’s fields are described in Save an automation draft. These operations need the owner or a manager of the workspace. The same tools are in the Devic MCP (https://devic.mcp.devic.ai/mcp), so an assistant like Claude can build an automation in a conversation.

Access

An API key restricted to some endpoints needs the Workspaces group (/v1/workspaces/*) in its allowed endpoints. An OAuth app needs the workspaces:read or workspaces:write scopes, or a platform:* scope.
The complete list of operations is in the API reference, under Workspaces.