> ## Documentation Index > Fetch the complete documentation index at: https://docs.custral.com/llms.txt > Use this file to discover all available pages before exploring further. # Create or update a record > Write a record by an identifying property: the record whose `matchOn` property holds the value in `fields` is updated, or created when none does. Send the same call twice and you get one record. `createFields` are written only when the record is created, so a first stage or owner never overwrites what people have changed since. **Requires scope:** `records:write`. The match is exact and reads committed data, so an upsert straight after a create finds it. Two upserts of the same value at once are serialised, not duplicated. When two or more records already hold the value the call fails with `match_ambiguous` and writes nothing; update the one you mean by its id. `matchOn` must be a text, email, phone or website property (`match_property_invalid` otherwise), and `fields` must include its value (`match_value_missing`). Fields behave exactly as on create: unknown keys come back in `ignoredFields`, and an unknown option label fails with `option_not_found`. ## OpenAPI ````yaml /openapi-v1.json post /v1/records/{object}/upsert openapi: 3.1.0 info: title: Custral API version: v1 description: >- The curated, versioned, API-key-authenticated public REST surface (`/v1`). Every endpoint here is what the official SDKs (`@custral/sdk`) and the MCP server are built on. Authenticate with a secret API key (`sk_…`) created in **Settings → Applications**. contact: name: Custral Support email: hello@custral.com url: https://custral.com license: name: Proprietary url: https://custral.com servers: - url: https://api.custral.com description: Production security: - ApiKey: [] tags: - name: Identity description: Introspect the calling API key. - name: Records description: Create, list, retrieve, and update records on any object. - name: Objects description: Read the object (table) schema of your workspace. - name: Conversations description: View, manage, and ingest conversations and their messages. - name: MCP description: Introspect the Model Context Protocol tool surface for a key. - name: Documents description: Read record notes / page documents as markdown. - name: Connectors description: The MCP servers Stella can use tools from. paths: /v1/records/{object}/upsert: post: tags: - Records summary: Create or update a record description: >- Write a record by an identifying property: the record whose `matchOn` property holds the value in `fields` is updated, or created when none does. Send the same call twice and you get one record. `createFields` are written only when the record is created, so a first stage or owner never overwrites what people have changed since. **Requires scope:** `records:write`. The match is exact and reads committed data, so an upsert straight after a create finds it. Two upserts of the same value at once are serialised, not duplicated. When two or more records already hold the value the call fails with `match_ambiguous` and writes nothing; update the one you mean by its id. `matchOn` must be a text, email, phone or website property (`match_property_invalid` otherwise), and `fields` must include its value (`match_value_missing`). Fields behave exactly as on create: unknown keys come back in `ignoredFields`, and an unknown option label fails with `option_not_found`. operationId: upsertRecord parameters: - name: object in: path required: true description: >- The target object — its id (`obj_…`), key, or name (e.g. `contacts`). schema: type: string example: contacts requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpsertRecordBody' example: matchOn: email fields: email: jane@acme.com full_name: Jane Doe createFields: status: Lead responses: '200': description: The record's id, and whether it was created or updated. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/UpsertRecordResult' reqId: $ref: '#/components/schemas/RequestId' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' components: schemas: UpsertRecordBody: type: object required: - matchOn - fields properties: matchOn: type: string description: >- The property that identifies the record — its id, key, or name. Must be a text, email, phone, or website property, and `fields` must carry its value. example: email fields: type: object additionalProperties: true description: >- A `{property: value}` map, as on create. Select and status values may be option labels. createFields: type: object additionalProperties: true description: >- A `{property: value}` map written only when the upsert creates the record, merged over `fields`; ignored when it updates one. Use it for a first stage or owner that people may change later. name: type: string description: An optional record name. UpsertRecordResult: type: object properties: id: type: string description: The record written (`rec_…`). action: type: string enum: - created - updated description: Whether a new record was made or the matching one was updated. ignoredFields: type: array items: type: string description: Field keys that matched no property and were dropped. droppedRelationTargets: type: array items: type: object properties: field: type: string dropped: type: integer description: >- Relation fields whose targets could not be linked, on a create. Empty on an update. RequestId: type: string description: >- A per-request id (`req_…`). Quote it to support when reporting a problem. example: req_2a1f9c8e7b6d5 Error: type: object description: >- The failure envelope. Every error carries a machine-readable `code` and the `reqId` of the failing request. properties: error: type: object properties: code: type: string example: insufficient_scope required: - code reqId: $ref: '#/components/schemas/RequestId' required: - error responses: InvalidRequest: description: 'The request body failed validation (`code: validation_failed`).' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: validation_failed reqId: req_2a1f9c8e7b6d5 Unauthorized: description: >- The API key is missing, unknown, inactive, or expired (`code: invalid_api_key`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key reqId: req_2a1f9c8e7b6d5 Forbidden: description: >- The key lacks the scope this endpoint requires (`code: insufficient_scope`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_scope reqId: req_2a1f9c8e7b6d5 NotFound: description: 'The object or record was not found (`code: not_found`).' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found reqId: req_2a1f9c8e7b6d5 RateLimited: description: >- Rate limited (`code: rate_limited`). Honour the `RateLimit-Reset` / `Retry-After` headers. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited reqId: req_2a1f9c8e7b6d5 securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: sk_... description: >- A Custral **secret** API key (`sk_…`), created in Settings → Applications. Sent as `Authorization: Bearer sk_…`. The `X-Api-Key: sk_…` header is also accepted and takes precedence. Never expose a secret key in a browser. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.