# Writes

URL: https://developers.uidu.org/docs/foundations/writes

> How create / update / delete work in @uidu/client and the uidu CLI — auth, input shape, error handling, and the per-entity capability matrix.

Beyond reading, `@uidu/client` exposes **authoring** functions — `createX` / `updateX` /
`deleteX` — for provisioning and editing workspace content. The `uidu` CLI wraps the same
functions as `<entity> create|update|delete`.

## Auth: every write needs a Bearer token

Writes authenticate as an account (`apiKey`), so they run on your server — a server action, route
handler, RSC or script — or from the CLI, never in the browser. That includes the visitor-facing
ones: a form response or a donation is submitted from a server action. See
[Authentication](https://developers.uidu.org/docs/foundations/authentication.md).

## Input shape

Every mutation takes a single `input` object. `create` carries `attributes`; `update` adds the
`id`; `delete` takes just the `id`:

```ts
import { createCourse, updateCourse, deleteCourse } from '@uidu/client';

await createCourse(client, { input: { attributes: { name: 'Onboarding' } } });
await updateCourse(client, { input: { id, attributes: { name: 'Onboarding v2' } } });
await deleteCourse(client, { input: { id } });
```

From the CLI:

```bash
uidu courses create --name "Onboarding"
uidu courses update <id> --attributes '{"name":"Onboarding v2"}'
uidu courses delete <id>
```

## Always check `errors`

Mutations resolve to a payload with an `errors` array and the affected record. A &#x2A;*non-empty
`errors`** means a validation failure — the record is unchanged.

```ts
const result = await createCourse(client, { input: { attributes: { name: 'Onboarding' } } });
if (result?.errors?.length) {
  // handle validation messages (result.errors[].name)
} else {
  result?.course?.id;
}
```

The CLI exits non-zero and prints the errors when the array is non-empty.

## Capability matrix

Not every entity supports every verb — this reflects what the client and CLI expose today,
generated from the CLI's resource registry. Beyond these, the CMS (`page`, `block`, `field`)
and provisioning (`workspace`, `project`) commands have their own verbs — see
[CLI commands](https://developers.uidu.org/docs/tools/cli/commands.md) — and any tool-flagged backend action can be run with
`executeAction` / `uidu tools call <key>`.

| Entity                | list | get | create | update | delete |
| --------------------- | :--: | :-: | :----: | :----: | :----: |
| `events`              |   ✓  |  ✓  |    ✓   |    ✓   |    —   |
| `attendances`         |   —  |  —  |    ✓   |    —   |    —   |
| `stories`             |   ✓  |  ✓  |    ✓   |    ✓   |    —   |
| `donations`           |   ✓  |  ✓  |    ✓   |    ✓   |    ✓   |
| `courses`             |   ✓  |  ✓  |    ✓   |    ✓   |    ✓   |
| `forms`               |   ✓  |  ✓  |    ✓   |    ✓   |    ✓   |
| `contacts`            |   ✓  |  ✓  |    ✓   |    —   |    ✓   |
| `deals`               |   ✓  |  ✓  |    ✓   |    ✓   |    —   |
| `goals`               |   ✓  |  ✓  |    —   |    ✓   |    —   |
| `timeframes`          |   ✓  |  —  |    —   |    —   |    —   |
| `employees`           |   ✓  |  —  |    ✓   |    ✓   |    —   |
| `employments`         |   —  |  —  |    ✓   |    ✓   |    ✓   |
| `offices`             |   ✓  |  —  |    —   |    —   |    —   |
| `roles`               |   ✓  |  —  |    —   |    —   |    —   |
| `ccnls`               |   ✓  |  —  |    ✓   |    —   |    —   |
| `bookings`            |   ✓  |  ✓  |    —   |    —   |    —   |
| `calls`               |   ✓  |  ✓  |    —   |    —   |    —   |
| `jobs`                |   ✓  |  ✓  |    —   |    —   |    —   |
| `applications`        |   ✓  |  —  |    ✓   |    —   |    —   |
| `campaigns`           |   ✓  |  ✓  |    —   |    —   |    —   |
| `kb-collections`      |   ✓  |  ✓  |    ✓   |    ✓   |    ✓   |
| `kb-articles`         |   ✓  |  ✓  |    ✓   |    ✓   |    ✓   |
| `channel`             |   ✓  |  ✓  |    ✓   |    ✓   |    ✓   |
| `time-clocks`         |   —  |  —  |    ✓   |    —   |    —   |
| `compensations`       |   —  |  —  |    ✓   |    ✓   |    ✓   |
| `tasks`               |   —  |  —  |    ✓   |    ✓   |    ✓   |
| `benefits`            |   —  |  —  |    ✓   |    —   |    —   |
| `benefit-enrollments` |   —  |  —  |    ✓   |    —   |    —   |
| `notes`               |   —  |  —  |    ✓   |    ✓   |    ✓   |
| `projects`            |   ✓  |  —  |    —   |    —   |    —   |
| `sites`               |   —  |  —  |    ✓   |    —   |    —   |
| `spaces`              |   —  |  —  |    ✓   |    ✓   |    ✓   |

See the [CLI commands](https://developers.uidu.org/docs/tools/cli/commands.md) for the read verbs too, and
[Schema](https://developers.uidu.org/docs/reference/schema.md) for the `*Attributes` input fields per entity.

## API at a glance

Every `@uidu/client` function in **Provisioning & actions**, generated from the source — the [full reference](https://developers.uidu.org/docs/reference/client.md#provisioning) has the rest of the SDK.

| Function                                                                                                        | Kind  | Auth   | CLI                     | Description                                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------- | ----- | ------ | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`createWorkspace`](https://github.com/uidu-org/api.js/blob/main/packages/client/src/system.ts)                 | write | Bearer | `workspace create`      | Create a workspace owned by the authenticated account (`attributes.name`, `subdomain`…). Returns the payload (with `errors`) or null.                       |
| [`executeAction`](https://github.com/uidu-org/api.js/blob/main/packages/client/src/actions.ts)                  | write | Bearer | `tools call`            | Run any backend action by `key` (an `ActionKey` flagged `of_kind_tool_key`), with optional `id` and `attributes`; returns `{ result, errors }` or null.     |
| [`generateWorkspaceApiCredentials`](https://github.com/uidu-org/api.js/blob/main/packages/client/src/system.ts) | write | Bearer | `workspace credentials` | Rotate + return a workspace's API credentials (apiKey/apiSecret). Operates on the current workspace. Use the returned credentials to wire a scaffolded app. |