---
title: "Create a database record"
method: POST
path: "/apps/{appRef}/data/collections/{collection}/records"
tags: ["Data"]
---

# Create a database record

`POST /apps/{appRef}/data/collections/{collection}/records`

## Request

- Base URL: `https://api.percher.run`
- URL: `https://api.percher.run/apps/{appRef}/data/collections/{collection}/records`
- Auth: HTTP bearer

Owner only. Requires the app activation gate and a full API token or an OAuth grant with live per-app data access. Uses the chosen per-app identity and its PocketBase rules. Only explicit full access bypasses them. Unset reads as a visitor and refuses writes. Responses exclude hidden fields. Maximum body 262144 bytes; response 1048576 bytes. Readwrite access required. A client id makes duplicate creates detectable. A 502 DATA_WRITE_OUTCOME_UNKNOWN (lost, 5xx, unreadable, oversized or timed-out reply) may have completed; check before retrying.

## Path parameters

- `appRef` string, required
- `collection` string, required

## Request body

- object
  - `data` object, required
  - `id` string

## Response `201`

Created record

## Other responses

- `400`: PB_VALIDATION, PB_CONFLICT_UNSUPPORTED, DATA_FIELD_UNSUPPORTED, NOT_POCKETBASE, DATA_QUERY_INVALID
- `401`: UNAUTHORIZED
- `403`: DATA_COLLECTION_FORBIDDEN, OAUTH_DATA_ACCESS_REQUIRED, DATA_TOOLS_NOT_ENABLED, PB_RULE_DENIED, DATA_ACT_AS_REQUIRED, DATA_ACT_AS_UNAVAILABLE, TOKEN_SCOPE_FORBIDDEN, TOKEN_APP_FORBIDDEN, OAUTH_SCOPE_FORBIDDEN
- `404`: PB_RECORD_NOT_FOUND, APP_NOT_FOUND
- `405`: METHOD_NOT_ALLOWED
- `409`: PB_CONFLICT, APP_DELETING
- `413`: DATA_RESPONSE_TOO_LARGE, DATA_SCHEMA_TOO_LARGE, PAYLOAD_TOO_LARGE
- `429`: DATA_RATE_LIMITED
- `502`: PB_BRIDGE_UNAVAILABLE: the read failed, or the write was refused before it was sent. DATA_WRITE_OUTCOME_UNKNOWN: the write may have completed; check the record and never retry it automatically.
- `503`: PB_VERSION_UNSUPPORTED, PB_AUTH_FAILED, PB_NOT_RUNNING, PLATFORM_READ_ONLY
- `504`: DATA_QUERY_TIMEOUT

---

[API](https://skmtc.dev/percher/apis/percher-api.md) · [All operations](https://skmtc.dev/percher/apis/percher-api/llms.txt) · [OpenAPI document](https://skmtc.dev/percher/apis/percher-api/revisions/d9e7089c21e5?raw)