/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.
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:
searchignores case and accents, and every word must appear.unread=truekeeps threads with messages from others since your last read, or that were marked unread.- Results come newest activity first, paginated with
offsetandlimit. - Each row carries
unreadCount,unreadMentionCount,waitingForMe(a question or an approval waiting for you) andactiveRunCount.
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 …/readfor 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:
clientMessageIdmakes them safe. The same id and body return the same message. @everybody: add{ "kind": "everyone", "id": "everyone", "label": "everybody" }tomentionsand@everybodyto 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
workspaceIdwith the usual thread endpoints to read, write, mark read or download files. It isnulluntil 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) gets403 DIRECT_MESSAGES_REQUIRE_USER. GET /v1/workspaces/threads?kind=directlists them among the rest.
When the assistant waits for you
A run inwaiting_input asked a question. A run in waiting_approval wants to
use a tool that needs approval.
POST …/invocations/{runId}/{action}:
answer:{ revision, inputId, response: { answers } }, orskipped: trueto skip the questions.approve:{ revision, actionId }, whereactionIdis the run’srequestedAction.id.cancelandretrytake the same route.
revision returns 409: read the thread again and retry. The CLI fills
in revision, inputId and actionId for you.
Files and documents
Content-Disposition.
Configure a workspace
Settings, members, assistants, knowledge and skills, rules, core memory and automations are all available: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
--scope workspace).3
Choose the event or the schedule
4
Grant tools and find the destination threads
5
Save the draft
6
Activate
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.