---
title: "Record actions"
description: "Read and modify the records of all tables described by TCA through the REST API, also in workspaces."
canonical: records.html
navigation-title: "Records"
---

<a id="usage-records"></a>

<a id="record-actions"></a>

# Record actions

- [FlexForm fields](#flexform-fields)
- [Workspaces](#workspaces)

You can read and change the records of all tables in TCA. TYPO3 derives the JSON
Schema of the input and the output of these actions from TCA, for each table
and record type. The OpenAPI document thus shows the fields of a record. A
relation is a reference with `_schema` and `uid`. System properties, for example
the language and the workspace version, are in `_system`. All paths are below
`/typo3/api/v1/`.

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `records/{schema}` | Lists the records of a table: `uid`, `pid`, label, record type, visibility and language of each record. Filter with `search` (label field), `pid`, `type` (for example the `CType` of `tt_content`) and `language`. Use `limit` (1 to 200, default 50) and `cursor` for pagination. `cursor` takes the `next` value of the previous page. |
| `GET` | `records/{schema}/{identifier}` | Gets a record by its uid, with all fields that the user can read. |
| `POST` | `records/{schema}/{pid}` | Creates a record on the given page, with inline children. |
| `PATCH` | `records/{schema}/{identifier}` | Updates a record. Only the given fields change. |
| `DELETE` | `records/{schema}/{identifier}` | Deletes a record. |

The record in the request body needs `_schema` with the name of the table. If it
does not agree with the path, the status is `400`.

Change the header of a content element

```bash
curl -X PATCH 'https://example.org/typo3/api/v1/records/tt_content/42' \
    -H 'Authorization: Bearer <token>' \
    -H 'Content-Type: application/json' \
    -d '{"record": {"_schema": "tt_content", "header": "New header"}}'
```

When you read, the table, field and page permissions of the backend user apply.
TYPO3 writes records with the `DataHandler`, which does all of its
permission checks.

Records of tables for administrators (`adminOnly`), for example backend users,
also need the scope `admin`. Without this scope, the status is `403`, and the
response does not contain inline children of such tables. A record that you
read never contains passwords. You can only write passwords.

<a id="usage-flexforms"></a>

<a id="flexform-fields"></a>

## FlexForm fields

A field of type `flex` is an object. Its keys combine the sheet and the field
name of the FlexForm, for example `sDEF/settings.limit`. TYPO3 derives its JSON
Schema from the data structure of the record type, so the available keys depend
on the type of the record. Checkboxes and numbers have their scalar types. A
section is a list of objects, and each object has the name of its container as
key. You can read relations in FlexForms as references with `_schema` and `uid`,
but you cannot write them.

FlexForm field with a section

```json
{
    "sDEF/settings.title": "Title",
    "sDEF/settings.limit": 5,
    "sItems/settings.items": [
        {"link": {"title": "Home", "url": "t3://page?uid=1"}},
        {"divider": {"label": "More"}}
    ]
}
```

An update changes only the given keys of the FlexForm. A given section replaces
the stored section completely.

<a id="usage-workspaces"></a>

<a id="workspaces"></a>

## Workspaces

All record actions accept the query parameter `workspace`. It selects the
workspace of the request, for example `?workspace=0` for the live workspace. The
default is the current workspace of the backend user. If the user has no access
to the given workspace, the status is `403`. The stored workspace of the user
does not change.