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

> ## Agent Instructions
> The docs are served at https://docs.devias.io. Every path in these docs is relative to that root: /llms.txt is https://docs.devias.io/llms.txt.
> Devias is an open-source platform that works as an operating system for a business: a core (records, views, workflows, agents, permissions) with installable modules.
> Pages are typed by folder. concepts/ explains what things are, guides/ gives procedures, reference/ is exhaustive (SDK, CLI, HTTP API), operate/ covers hosting. Use /start/glossary for exact terms.
> Every id in a module (module, object, field, view, action, workflow, step, connection, variable, event, policy) is a uuid. Generate them with `devias id <count>`. Never invent dotted or readable ids.
> Run `devias plan` and read its output before `devias apply`. Apply only what the plan says.
> The OpenAPI document, including the routes of the modules in the reference setup, is at /reference/api/openapi.json.
> Devias is young and changes quickly. If a page and the source repository (github.com/devias-io/devias) disagree, the repository is right.

# TypeScript SDK

> @devias/sdk is the typed TypeScript client the studio uses. How to create a client (baseUrl, workspaceId, apiKey), the areas it offers (records, metadata, modules, workflows, tasks, documents, comments, activity, notifications, events, ai) and how errors are thrown as DeviasApiError.

`@devias/sdk` is the client the studio itself uses. It calls the Devias HTTP API, listens for live changes and provides a query builder. It is written in TypeScript, so every method and record shape is typed.

The SDK lives in the repository as the `@devias/sdk` workspace package. A package that uses it adds it as a `workspace:*` dependency.

## Create a client

```ts theme={"dark"}
import { createClient } from '@devias/sdk';

const client = createClient({
  baseUrl: 'http://localhost:3000',
  workspaceId: 'your-workspace-id',
  apiKey: process.env.DEVIAS_API_KEY,
});
```

| Option | What it is |
| - | - |
| `baseUrl` | Where the Devias server runs. |
| `workspaceId` | The workspace every call is about. Copy it from **Settings → General**. |
| `apiKey` | Sent with each request. In a browser, leave it out and the signed-in session cookie is used instead. |

An API key is created in **Settings → API keys**. A key made there can read records. See [Authentication](https://docs.devias.io/reference/api/authentication.md).

`createWorkspaceApi` with only a `baseUrl` lists the workspaces a person can open, and creates one.

## Areas of the client

Everything hangs off one object, grouped by area.

| Area | What you do with it |
| - | - |
| `records` | List, get, create, update, delete, upsert and look up records. |
| `metadata` | Read the schema, and manage objects, fields, views, layouts and navigation. |
| `modules` | List, plan, apply and uninstall modules, run their actions, manage connections. |
| `workflows` | Create, run and inspect workflows and their runs. |
| `tasks`, `documents` | The work and the pages of the workspace. |
| `comments`, `activity` | A record's comments and history. |
| `notifications` | Read the signed-in person's notifications, and notify others. |
| `events` | Subscribe to live changes. |
| `ai` | Conversations with agents. |

## Errors

Every failure is thrown as a `DeviasApiError`, with a `status`, a `code` such as `NOT_FOUND` or `VALIDATION`, a `message`, and sometimes `details`.

```ts theme={"dark"}
try {
  await client.records.get('person', '01a17356-5c6a-71ce-8397-1fa843605aae');
} catch (error) {
  if (error instanceof DeviasApiError && error.code === 'NOT_FOUND') {
    // handle it
  }
}
```

See [Errors](https://docs.devias.io/reference/api/errors.md) for every code.

## Related

* [Records and queries](https://docs.devias.io/reference/sdk/records-and-queries.md): read and write data.
* [Metadata and modules](https://docs.devias.io/reference/sdk/metadata-and-modules.md): the schema and module installation.
* [Events and notifications](https://docs.devias.io/reference/sdk/events-and-notifications.md): live changes.
* [Mock backend](https://docs.devias.io/reference/sdk/mock-and-testing.md): work without a server.


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