# Apps

> Read and write the records in apps built in PlaybookOps.

Apps built in PlaybookOps store their data as **records** in **collections**. The API works on Live records, the ones people see in the published app. A key can reach an app when its owner can open it, or edits it.

## Learn an app's shape

```bash
curl https://developers.playbookops.ai/v1/apps \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"

curl https://developers.playbookops.ai/v1/apps/APP_ID \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
```

Each collection lists its fields with their `type`, whether they're `required`, their `options`, and which collection a link field points to (`links_to`).

## Find records

```bash
curl "https://developers.playbookops.ai/v1/apps/APP_ID/collections/deals/records?filter=stage:eq:won&filter=amount:gt:1000&sort=-amount" \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
```

Repeat `filter` as `field:op:value`:

| Op | Means |
| --- | --- |
| `eq`, `neq` | Equals, doesn't equal |
| `gt`, `lt` | Greater than, less than |
| `in` | One of several values, separated by commas |
| `contains` | Text contains |
| `has` | A multi-select or many-link field includes the value |

`sort` takes a field name; put `-` in front for largest or latest first.

## Add and update records

With `apps:write`:

**curl**

```bash
curl -X POST https://developers.playbookops.ai/v1/apps/APP_ID/collections/deals/records \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" -H "Content-Type: application/json" \
  -d '{"data": {"name": "Acme renewal", "amount": 12000, "stage": "proposal"}}'

curl -X PATCH https://developers.playbookops.ai/v1/apps/APP_ID/collections/deals/records/RECORD_ID \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" -H "Content-Type: application/json" \
  -d '{"data": {"stage": "won"}}'
```

**Python**

```python
deal = api.post(
    f"/apps/{app_id}/collections/deals/records",
    json={"data": {"name": "Acme renewal", "amount": 12000, "stage": "proposal"}},
).json()

api.patch(f"/apps/{app_id}/collections/deals/records/{deal['id']}", json={"data": {"stage": "won"}})
```

Records are checked against the app's fields exactly as in the app: required fields, types, options and links. A record that doesn't fit returns `422` naming each field. Fields starting with `_` are reserved, and a record can be up to 100 KB.

## Reference

| Action | Endpoint | MCP tool |
| --- | --- | --- |
| List apps | `GET /v1/apps` | `list_apps` |
| An app's collections and fields | `GET /v1/apps/{id}` | `get_app` |
| Find records | `GET /v1/apps/{id}/collections/{collection}/records` | `list_app_records` |
| One record | `GET …/records/{record_id}` | `get_app_record` |
| Add a record | `POST …/records` | `create_app_record` |
| Update a record | `PATCH …/records/{record_id}` | `update_app_record` |

Every parameter is in the [API reference](https://developers.playbookops.ai/reference/apps).
