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

# Overview

<RequestExample>
  ```shell Create a single record theme={null}
  curl -X POST \
    https://api.sequin.io/v1/mutations/run \
    -H 'content-type: application/json' \
    -H 'authorization: Bearer {token}' \
    -d '{
          "kind": "create",
          "sync_id": "my-sync-id",
          "collection_id": "salesforce:contact",
          "records": [
            {
              "data": {
                "FirstName": "Paul",
                "LastName": "Atreides",
                "Email": "paul@arrakis.org"
              }
            }
          ]
        }'
  ```

  ```shell Update multiple records theme={null}
  curl -X POST \
    https://api.sequin.io/v1/mutations/run \
    -H 'content-type: application/json' \
    -H 'authorization: Bearer {token}' \
    -d '{
          "kind": "update",
          "sync_id": "my-sync-id",
          "collection_id": "salesforce:contact",
          "records": [
            {
              "upstream_id": "0031U00000Qn2ZVQAZ",
              "data": {
                "FirstName": "Paul",
                "LastName": "Atreides",
                "Email": "paul@arrakis.org"
              }
            },
            {
              "upstream_id": "0031U00000Qn2ZVQBA",
              "data": {
                "FirstName": "Duncan",
                "LastName": "Idaho",
                "Email": "duncan@arrakis.org"
              }
            }
          ]
        }'
  ```

  ```shell Delete a record theme={null}
  curl -X POST \
    https://api.sequin.io/v1/mutations/run \
    -H 'content-type: application/json' \
    -H 'authorization: Bearer {token}' \
    -d '{
          "kind": "delete",
          "sync_id": "my-sync-id",
          "collection_id": "salesforce:contact",
          "upstream_ids": [
            "0031U00000Qn2ZVQAZ",
            "0031U00000Qn2ZVQBA"
          ]
        }'
  ```
</RequestExample>

## Mutation API

The Mutation API lets you mutate one or more records synchronously:

```bash theme={null}
POST /v1/mutations/run
```

For [creates](/mutations/create) and [updates](/mutations/update), you'll send Sequin a partial [record](/core-concepts#records). For creates, the partial record contains only the `data` key:

```json PartialRecord theme={null}
{
  "data": {
    "FirstName": "Paul",
    "LastName": "Atreides",
    "Email": "paul@arrakis.org"
  }
}
```

For updates, the partial record contains the `upstream_id` and `data` keys:

```json PartialRecord theme={null}
{
  "upstream_id": "0031U00000Qn2ZVQAZ",
  "data": {
    "FirstName": "Paul",
    "LastName": "Atreides",
    "Email": "paul@arrakis.org"
  }
}
```

For [deletes](/mutations/delete), you'll send Sequin a list of `upstream_id`s.

<Note>
  Note that the shape of the `data` payload in creates and updates is the same shape that Sequin uses throughout the system for that collection. If ever in doubt, copy and paste the `data` field from a record or event and use it as the starting point for your mutation.
</Note>

### Awaiting consumers

By default, Sequin applies mutations to the upstream API and to your streams, then returns a response. You can specify that you want your request to also block until the mutations have been applied to one or more consumers. This is useful if you need a read-after-write (or "read your writes") workflow. For example, you might want to create a Salesforce Contact via the Mutation API, then re-render a view that pulls it from your database.

To await consumers, you can include the optional `await_consumer_ids` property in your request. The value of `await_consumer_ids` is a list of one or more consumer IDs. You can find the ID of a consumer in the Sequin console or via the Management API.

By default, Sequin will wait for consumers for up to 30 seconds. You can specify how long you want Sequin to wait by including an optional `await_consumers_timeout` property in your request. The value of `await_consumers_timeout` is the number of milliseconds to wait for consumers to finish processing the mutations, after the API mutation has succeeded.

If Sequin times out while waiting for consumers, it will return a `500` response with an error message:

```json 500 Internal Server Error theme={null}
{
  "error": "Error: Timed out waiting for consumers: {consumer_id}",
  "docs": [ ... ]
}
```

<Warning>
  If the mutation was not idempotent (e.g. a create mutation), in this instance it is **not** safe to retry.
</Warning>