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

# Workspace records

> Create and manage records belonging to a workspace Object.

Workspace Objects use the record endpoints below. Platform Objects keep their
existing endpoints, such as `/v1/workers`.

These endpoints require Objects enabled and a verified administrator.
Reads require `records:read`; writes also require `records:write`.
Object-definition administration permissions are separate. Access is currently
workspace-wide; grants limited to particular Object types are not yet supported.

| Action  | Endpoint                               |
| ------- | -------------------------------------- |
| Create  | `POST /v1/objects/{slug}`              |
| List    | `GET /v1/objects/{slug}`               |
| Get     | `GET /v1/objects/{slug}/{id}`          |
| Update  | `PATCH /v1/objects/{slug}/{id}`        |
| Archive | `POST /v1/objects/{slug}/{id}/archive` |

Use the unprefixed Object slug, such as `computers`, for `{slug}`. The record's
`object` value uses the full key, `objects.computers`.
Create the definition and its Attributes before writing their values.

### Create and update

Request bodies contain Attribute keys directly. Omitted Attributes remain
unchanged during updates; `null` clears a value. All Attributes are optional,
so an Object without Attributes can still have records. There is no required
Name attribute.

```http theme={null}
POST /v1/objects/computers
Content-Type: application/json

{"serial_number": "ABC-123", "purchased_on": "2026-09-06"}
```

Create returns HTTP 201; get, update, and archive return HTTP 200 with the same
record shape:

```json theme={null}
{
  "id": "obj_computers_example",
  "object": "objects.computers",
  "workspace": "wsp_example",
  "created": "2026-09-06T12:00:00Z",
  "updated": "2026-09-06T12:00:00Z",
  "archived": false,
  "serial_number": "ABC-123",
  "purchased_on": "2026-09-06"
}
```

Envelope fields are read-only. Unknown keys or invalid values reject the whole
write. Saved values follow Attribute IDs internally: changing an Attribute key
changes its public JSON key without losing values. Archived Attributes are
omitted from reads. Archived select options remain readable on existing records
but cannot be assigned again.

### References

Reference Attributes point to one record of a chosen Object. Set the target
Object when creating the Attribute in Manage, then write a record ID:

```http theme={null}
PATCH /v1/objects/computers/obj_computers_example
Content-Type: application/json

{"assigned_to": "wr_example"}
```

The value reads back as the same ID. The target must belong to the configured
Object and the same workspace, and the caller must be able to read it. This
works with platform targets such as Workers and workspace Objects alike.
For example, assigning a Worker requires `workers:read` in addition to the
source record's write permissions.

Archiving a target preserves existing links, but prevents new assignments.
Omitting the Attribute preserves the link; `null` clears it. An unchanged
Reference can be submitted again after its target is archived. API reads retain
the stored ID; Manage only displays target labels and links when the caller can
read the target. This release supports one-way, single-record References.

### List and archive

Lists return `data` and, when there is another page, `cursor`. They accept the
standard `limit`, `cursor`, `starting_after`, and `ending_before` parameters.
`count=true` returns only `{"total": 12}` and cannot be combined with pagination.

Lists include active records by default. Use `archived=true` to list archived
records. Archived records remain available by ID; archiving retains their
values and repeating the archive request has no effect. Archived records
cannot be updated. Restoration is not yet available.

### Tools

Tool discovery exposes five tools per visible workspace Object, for example
`objects_computers_create`, `objects_computers_get`,
`objects_computers_list`, `objects_computers_update`, and
`objects_computers_archive`. Create and update take flat, typed Attribute
arguments; get, update, and archive also take `id`. Tool schemas reflect the
caller's workspace and current Attributes.