> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces from the API and the CLI

> Read and search threads, find what is unread, write as a person or as an integration, answer assistants, download files and configure workspaces — with the same permissions as the app.

Everything a person does in a [workspace](https://docs.devic.ai/devic/workspaces/index.md) can also be
done from code, under `/v1/workspaces` of the public API or with
`devic workspaces` (alias `devic ws`) in the [CLI](https://docs.devic.ai/devic/cli/index.md). 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.

| Credential | `X-Devic-User` header | Acts as |
| - | - | - |
| A person's token (CLI login, OAuth app) | — | That person |
| API key | userUID or email of a person of the key's account | That person, with **their own** permissions |
| API key | not sent | The **account integration**, shown as "API" |

* **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.

```bash theme={null}
devic ws me                                   # person or integration, and the origin its messages carry
devic ws --as ana@acme.com me                 # act for a person (or: export DEVIC_USER=ana@acme.com)
```

```http theme={null}
GET https://api.devic.ai/v1/workspaces/me
Authorization: Bearer YOUR_API_KEY
X-Devic-User: ana@acme.com
```

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

```bash theme={null}
devic ws list --search ventas --summary          # with thread, unread and document counts
devic ws threads list --unread                   # unread threads across every workspace
devic ws threads list --search renovaciones      # matches the thread title or the workspace name
```

[`GET /v1/workspaces/threads`](https://docs.devic.ai/api-reference/endpoint/get-api-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

```bash theme={null}
devic ws threads get <wid> <tid>                    # latest messages and pending questions
devic ws threads messages <wid> <tid> --before 120  # an older page
devic ws threads messages <wid> <tid> --after 164   # only what is new
devic ws threads read <wid> <tid>                   # mark it read
```

* 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`](https://docs.devic.ai/api-reference/endpoint/post-api-v1-workspaces-wid-threads-tid-read)
  for that.

***

## Write, and wait for the assistant

```bash theme={null}
devic ws send <wid> <tid> "Resume la semana" --assistant <aid> --wait
```

```http theme={null}
POST /v1/workspaces/{wid}/threads/{tid}/messages
{ "text": "Resume la semana", "directedAssistantId": "<aid>", "clientMessageId": "weekly-2026-47" }
```

* **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

```bash theme={null}
devic ws dm list
devic ws dm send ana@acme.com "¿Revisas la factura?"
```

```http theme={null}
GET  /v1/workspaces/direct-messages            → { "workspaceId": "<space>", "items": [ … ] }
POST /v1/workspaces/direct-messages  { "email": "ana@acme.com" }   // or "userUID"
```

* 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.

```bash theme={null}
devic ws answer <wid> <tid> <runId> --answers '[{"id":"periodicidad","selected":["anual"]}]'
devic ws approve <wid> <tid> <runId>
```

Through the API, use
[`POST …/invocations/{runId}/{action}`](https://docs.devic.ai/api-reference/endpoint/post-api-v1-workspaces-wid-threads-tid-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

```bash theme={null}
devic ws files list <wid> <tid>
devic ws files download <wid> <tid> <fileId> --out ./out/   # never overwrites without --force
devic ws documents <wid> --search contrato
```

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:

```bash theme={null}
devic ws members set <wid> <userUID> --role member
devic ws skills attach <wid> <skillId>
devic ws rules set <wid> --file rules.md
devic ws memory add <wid> <aid> --section decisions --content "Prices are quoted in EUR" --pinned
devic ws automations list <wid>
```

Each needs the same [role](https://docs.devic.ai/devic/workspaces/index.md#roles) 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**

```bash theme={null}
devic ws automations capabilities <wid>    # app events, schedules, included model
devic ws automations destinations <wid>    # workspaces it may post to
devic ws automations connections <wid>     # connected accounts it may use
```

**2. Connect a missing app**

```bash theme={null}
devic ws integrations search <wid> "meeting recordings" --semantic
devic ws connections connect <wid> <app> --scope workspace
```

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**

```bash theme={null}
devic ws automations triggers <wid> --integration <app> --query "new recording"
devic ws automations trigger <wid> <slug>              # configuration and setup instructions
devic ws automations schedule-preview <wid> --data '{"expression":"0 9 * * 1-5","timezone":"Europe/Madrid"}'
```

**4. Grant tools and find the destination threads**

```bash theme={null}
devic ws automations connection-tools <wid> <connectionId>
devic ws automations find-threads <wid> <target> --query acme --search-in all
```

**5. Save the draft**

```bash theme={null}
devic ws automations create <wid> --name "Meeting summaries"
devic ws automations draft <wid> <id> --data plan.json
```

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

**6. Activate**

```bash theme={null}
devic ws automations activate <wid> <id> --included
```

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](https://docs.devic.ai/api-reference/endpoint/put-api-v1-workspaces-wid-automations-automationid-draft.md).
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

> [!NOTE]
>
> An API key restricted to some endpoints needs the **Workspaces** group
> (`/v1/workspaces/*`) in its [allowed endpoints](https://docs.devic.ai/devic/administration/api-keys.md).
> 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](https://docs.devic.ai/api-reference/endpoint/get-api-v1-workspaces.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.