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

# Update deals in batch

> Update up to 100 existing deals of one type in a group, each with the fields `PATCH /v1/groups/{groupId}/{objectType}/{objectId}` accepts. Each record is updated on its own: one that fails does not prevent the others from being updated.

`people` and `companies` **replace** the people and companies of the deal: you must provide the entire list, not just the ones you want to add. Leave them out to keep them unchanged. They are given by ID, and an unknown one, or one not in the group, is ignored, as in `PATCH /v1/groups/{groupId}/{objectType}/{objectId}`.

A record whose ID designates an object of another type, or of another group, fails as not found.

The records of one deal are merged into one update, in request order: the last value given for a field wins, and `customFieldValues` are merged field by field, the last value given for a custom field winning. The merged update is validated as a whole: if it is invalid, every record of that deal fails with that error. Each of those records gets its own result, with the deal as finally updated.

An object type that does not exist in the group fails the whole request with a `404`, whose message lists the object types of the group.

Update up to 100 existing deals in a group, identified by their `id`. Each record takes the same fields as [update a deal](/api-reference/deals/update-a-deal) and is updated on its own: a record that fails, for instance because of an unknown custom field, does not prevent the others from being updated. See [batch requests](/api-reference/batch-requests) for the 100-record limit and how to read the response. Each deal comes back in full, as in the response of [update a deal](/api-reference/deals/update-a-deal).

A batch targets one object type in one group, given by the path. An object type that does not exist in the group fails the whole request with a `404`, whose message lists the object types of the group. A record whose `id` designates an object of another type, or of another group, fails as not found. If the API key cannot update deals in the group, every record fails.

<Warning>
  `people` and `companies` **replace** the people and companies of the deal: you
  must provide the entire list, not just the ones you want to add. Leave them
  out to keep them unchanged.
</Warning>

People and companies are given by ID, and must already be in the group: an unknown one, or one not in the group, is ignored.

The records of one deal are merged into one update, in the order you sent them: the last value given for a field wins, and `customFieldValues` are merged field by field, the last value given for a custom field winning. The merged update is validated as a whole: if it is invalid, every record of that deal fails with that error. Each of those records gets its own result, with the deal as finally updated. This is not always the same as sending the records one after the other: a record with an invalid custom field value fails every record of its deal, including the earlier ones, which sent on their own would have been applied before it.

A record that succeeded but whose people, companies or custom field values could not all be set carries a `warnings` list explaining what was not applied.


## OpenAPI

````yaml post /v1/groups/{groupId}/{objectType}/batch/update
openapi: 3.1.0
info:
  title: Folk External API
  description: >-
    Folk's public REST API lets you manage workspaces, groups, contacts, and
    real-time triggers.
  version: '2025-06-09'
  contact:
    name: folk
    email: tech@folk.app
    url: https://folk.app
servers:
  - url: https://api.folk.app
    description: Folk's public API production base URL.
    x-internal: false
security: []
tags:
  - name: Companies
    description: Operations related to companies.
  - name: Credits
    description: Operations related to credits.
  - name: Deals
    description: Operations related to deals.
  - name: Groups
    description: Operations related to groups.
  - name: Group members
    description: Operations related to group members.
  - name: Group custom fields
    description: Operations related to group custom fields.
  - name: Interactions
    description: Operations related to interactions.
  - name: Notes
    description: Operations related to notes.
  - name: People
    description: Operations related to people.
  - name: Reminders
    description: Operations related to reminders.
  - name: Tasks
    description: Operations related to tasks.
  - name: Users
    description: Operations related to users.
  - name: Webhooks
    description: Operations related to webhooks.
paths:
  /v1/groups/{groupId}/{objectType}/batch/update:
    post:
      tags:
        - Deals
      summary: Update deals in batch
      description: >-
        Update up to 100 existing deals of one type in a group, each with the
        fields `PATCH /v1/groups/{groupId}/{objectType}/{objectId}` accepts.
        Each record is updated on its own: one that fails does not prevent the
        others from being updated.


        `people` and `companies` **replace** the people and companies of the
        deal: you must provide the entire list, not just the ones you want to
        add. Leave them out to keep them unchanged. They are given by ID, and an
        unknown one, or one not in the group, is ignored, as in `PATCH
        /v1/groups/{groupId}/{objectType}/{objectId}`.


        A record whose ID designates an object of another type, or of another
        group, fails as not found.


        The records of one deal are merged into one update, in request order:
        the last value given for a field wins, and `customFieldValues` are
        merged field by field, the last value given for a custom field winning.
        The merged update is validated as a whole: if it is invalid, every
        record of that deal fails with that error. Each of those records gets
        its own result, with the deal as finally updated.


        An object type that does not exist in the group fails the whole request
        with a `404`, whose message lists the object types of the group.
      operationId: batchUpdateDeals
      parameters:
        - schema:
            type: string
            minLength: 40
            maxLength: 40
          required: true
          description: >-
            The ID of the group the deals belong to. Can be retrieved from the
            [List groups](/api-reference/groups/list-groups) endpoint.
          example: grp_bc984b3f-0386-434d-82d7-a91eb6badd71
          name: groupId
          in: path
        - schema:
            type: string
            maxLength: 500
          required: true
          description: >-
            The name of a deal custom field that can be retrieved from the [List
            group custom
            fields](/api-reference/group-custom-fields/list-group-custom-fields)
            endpoint.
          example: Deals
          name: objectType
          in: path
        - schema:
            type: string
            maxLength: 255
            description: >-
              A unique key, such as a UUID, that makes retrying this request
              safe: a retry with the same key and body returns the original
              response without running the operation again. Keys are kept for 24
              hours after the request completes.
            example: 8e03978e-40d5-43e8-bc93-6894a57f9324
          required: false
          name: Idempotency-Key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                records:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        minLength: 40
                        maxLength: 40
                        description: The ID of the deal to update.
                      name:
                        type: string
                        maxLength: 1000
                        description: The name of the deal.
                        example: Project Alpha
                      companies:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              minLength: 40
                              maxLength: 40
                          required:
                            - id
                          additionalProperties: false
                        maxItems: 20
                        description: The companies associated with the deal.
                        example:
                          - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
                      people:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              minLength: 40
                              maxLength: 40
                          required:
                            - id
                          additionalProperties: false
                        maxItems: 20
                        description: The people associated with the deal.
                        example:
                          - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
                      customFieldValues:
                        type: object
                        additionalProperties:
                          anyOf:
                            - type: 'null'
                            - type: string
                              maxLength: 5000
                            - type: number
                              minimum: -1.7976931348623157e+308
                              maximum: 1.7976931348623157e+308
                            - type: array
                              items:
                                anyOf:
                                  - type: string
                                    maxLength: 500
                                  - type: object
                                    properties:
                                      id:
                                        type: string
                                        minLength: 40
                                        maxLength: 40
                                    required:
                                      - id
                                  - type: object
                                    properties:
                                      email:
                                        type: string
                                        maxLength: 254
                                    required:
                                      - email
                              maxItems: 1000
                            - type: 'null'
                        description: >-
                          The custom field values associated with the deal. The
                          format is the following:

                          ```json

                          {
                            "<customFieldName>": "<customFieldValue>"
                          }

                          ```


                          The format of the custom field value depends on the
                          type of the custom field:


                          - `textField`: string, eg: `"Foo"`

                          - `numericField`: number or numeric string, eg: `42`
                          or `"42"`

                          - `dateField`: ISO 8601 string (YYYY-MM-DD), eg:
                          `"2021-01-01"`

                          - `singleSelect`: string (option label), eg:
                          `"Active"`

                          - `multipleSelect`: array of strings (option labels),
                          eg: `["B2B", "B2C"]`

                          - `userField`: array of objects with either `id`
                          (workspace user id) or `email` (workspace user email)
                          property, eg: `[{"id":
                          "usr_a23373bb-5296-4c59-b2e8-8f121707d562"}, {"email":
                          "jane@example.com"}]`


                          Passing a `null` value or an empty array will unset
                          the custom field value.
                        properties: {}
                        example:
                          Status: Active
                          Deal value: '42000'
                          Close date: '2021-01-01'
                          Assignee:
                            - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6
                            - email: jane@example.com
                    required:
                      - id
                    additionalProperties: false
                    example:
                      id: obj_183ed5cc-3182-45de-84d1-d520f2604810
                      name: Project Alpha
                      people:
                        - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
                      customFieldValues:
                        Status: Won
                  maxItems: 100
              required:
                - records
              example:
                records:
                  - id: obj_183ed5cc-3182-45de-84d1-d520f2604810
                    name: Project Alpha
                    people:
                      - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
                    customFieldValues:
                      Status: Won
      responses:
        '200':
          description: The outcome of each record, with each updated deal.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-RateLimit-Limit-Burst:
              $ref: '#/components/headers/X-RateLimit-Limit-Burst'
            X-RateLimit-Remaining-Burst:
              $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
            X-RateLimit-Reset-Burst:
              $ref: '#/components/headers/X-RateLimit-Reset-Burst'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      results:
                        type: array
                        items:
                          oneOf:
                            - type: object
                              properties:
                                status:
                                  type: string
                                  enum:
                                    - succeeded
                                data:
                                  $ref: '#/components/schemas/Deal'
                                warnings:
                                  type: array
                                  items:
                                    type: string
                                  description: >-
                                    What could not be applied to this record
                                    although it succeeded, such as a group it
                                    could not be added to.
                              required:
                                - status
                                - data
                            - type: object
                              properties:
                                status:
                                  type: string
                                  enum:
                                    - failed
                                error:
                                  $ref: '#/components/schemas/BatchRecordError'
                              required:
                                - status
                                - error
                        description: >-
                          One result per record, in the order of `records`: the
                          first result is the outcome of the first record.
                    required:
                      - results
                    example:
                      results:
                        - status: succeeded
                          data:
                            id: obj_183ed5cc-3182-45de-84d1-d520f2604810
                            name: Project Alpha
                            companies:
                              - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
                                name: Tech Corp
                            people:
                              - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
                                fullName: John Doe
                            createdAt: '2021-01-01T00:00:00.000Z'
                            createdBy:
                              id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
                              fullName: John Doe
                              email: john.doe@example.com
                            customFieldValues:
                              Status: Active
                              Deal value: '42000'
                              Close date: '2021-01-01'
                              Assignee:
                                - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6
                                  fullName: Jane Doe
                                  email: jane@example.com
                        - status: failed
                          error:
                            code: NOT_FOUND
                            message: Not found.
                            documentationUrl: >-
                              https://developer.folk.app/api-reference/errors#not-found
                  deprecations:
                    type: array
                    items:
                      type: string
                    example:
                      - This field is deprecated
                required:
                  - data
              example:
                data:
                  results:
                    - status: succeeded
                      data:
                        id: obj_183ed5cc-3182-45de-84d1-d520f2604810
                        name: Project Alpha
                        companies:
                          - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
                            name: Tech Corp
                        people:
                          - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
                            fullName: John Doe
                        createdAt: '2021-01-01T00:00:00.000Z'
                        createdBy:
                          id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
                          fullName: John Doe
                          email: john.doe@example.com
                        customFieldValues:
                          Status: Active
                          Deal value: '42000'
                          Close date: '2021-01-01'
                          Assignee:
                            - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6
                              fullName: Jane Doe
                              email: jane@example.com
                    - status: failed
                      error:
                        code: NOT_FOUND
                        message: Not found.
                        documentationUrl: >-
                          https://developer.folk.app/api-reference/errors#not-found
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - bearerApiKeyAuth: []
components:
  headers:
    X-RateLimit-Limit:
      schema:
        type: integer
        example: 1000
      description: >-
        The maximum number of requests that you can make in the current rate
        limit window.
    X-RateLimit-Remaining:
      schema:
        type: integer
        example: 998
      description: The number of requests remaining in the current rate limit window.
    X-RateLimit-Reset:
      schema:
        type: integer
        example: 1747322958
      description: >-
        The time at which the current rate limit window resets, in UTC epoch
        seconds.
    X-RateLimit-Limit-Burst:
      schema:
        type: integer
        example: 20
      description: >-
        The maximum number of requests that you can make in the current burst
        rate limit window.
    X-RateLimit-Remaining-Burst:
      schema:
        type: integer
        example: 18
      description: The number of requests remaining in the current burst rate limit window.
    X-RateLimit-Reset-Burst:
      schema:
        type: integer
        example: 1747322902
      description: >-
        The time at which the current burst rate limit window resets, in UTC
        epoch seconds.
    RateLimit-Policy:
      schema:
        type: string
        example: '"default";q=600;w=60, "burst";q=20;w=2'
      description: >-
        The rate limit policies applied to the request, as defined by the IETF
        RateLimit header fields draft. `q` is the number of requests allowed per
        window and `w` the window length in seconds.
    RateLimit:
      schema:
        type: string
        example: '"default";r=598;t=42, "burst";r=18;t=1'
      description: >-
        The current usage of each rate limit policy, as defined by the IETF
        RateLimit header fields draft. `r` is the number of requests remaining
        and `t` the number of seconds until the window resets.
    Retry-After:
      schema:
        type: integer
        example: 60
      description: >-
        The number of seconds to wait before making a new request after hitting
        the rate limit.
  schemas:
    Deal:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: The name of the deal.
          example: Project Alpha
        companies:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
                description: The name of the company.
                example: Tech Corp
            required:
              - id
              - name
        people:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              fullName:
                type: string
                description: The name of the person.
                example: John Doe
            required:
              - id
              - fullName
        createdAt:
          type:
            - string
            - 'null'
          minLength: 20
          maxLength: 40
          description: The date and time the deal was created, in ISO format.
          example: '2021-01-01T00:00:00.000Z'
        createdBy:
          $ref: '#/components/schemas/User'
        customFieldValues:
          type: object
          additionalProperties:
            anyOf:
              - type: 'null'
              - type: string
                description: A custom field value as a string.
                example: Value 1
              - type: array
                items:
                  type: string
                description: An array of values for the custom field.
                example:
                  - Value 1
                  - Value 2
              - type: array
                items:
                  $ref: '#/components/schemas/User'
                description: An array of users associated with the custom field.
                example:
                  - id: usr_44b85098-441b-4d7f-9d72-c079b1caec45
                    fullName: Jane Doe
                    email: jane@example.com
                  - id: usr_a95a1b90-8e88-4855-bc29-d47b8e2704e1
                    fullName: John Doe
                    email: john@example.com
              - type: array
                items:
                  anyOf:
                    - type: object
                      properties:
                        id:
                          type: string
                        fullName:
                          type: string
                        entityType:
                          type: string
                          enum:
                            - person
                      required:
                        - id
                        - fullName
                        - entityType
                    - type: object
                      properties:
                        id:
                          type: string
                        fullName:
                          type: string
                        entityType:
                          type: string
                          enum:
                            - company
                      required:
                        - id
                        - fullName
                        - entityType
                    - type: object
                      properties:
                        id:
                          type: string
                        fullName:
                          type: string
                        entityType:
                          type: string
                          enum:
                            - object
                      required:
                        - id
                        - fullName
                        - entityType
                description: An array of relationships associated with the custom field.
                example:
                  - id: per_183ed5cc-3182-45de-84d1-d520f2604810
                    fullName: John Doe
                    entityType: person
                  - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
                    fullName: Tech Corp
                    entityType: company
              - type: 'null'
      required:
        - id
        - name
        - companies
        - people
        - createdAt
        - createdBy
        - customFieldValues
      description: A deal in the workspace.
      example:
        id: obj_183ed5cc-3182-45de-84d1-d520f2604810
        name: Project Alpha
        companies:
          - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
            name: Tech Corp
        people:
          - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
            fullName: John Doe
        createdAt: '2021-01-01T00:00:00.000Z'
        createdBy:
          id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
          fullName: John Doe
          email: john.doe@example.com
        customFieldValues:
          Status: Active
          Deal value: '42000'
          Close date: '2021-01-01'
          Assignee:
            - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6
              fullName: Jane Doe
              email: jane@example.com
    BatchRecordError:
      type: object
      properties:
        code:
          type: string
          example: NOT_FOUND
        message:
          type: string
          example: Not found.
        documentationUrl:
          type: string
          format: uri
          example: https://developer.folk.app/api-reference/errors#not-found
        details:
          type: object
          additionalProperties: true
      required:
        - code
        - message
        - documentationUrl
      description: Why this record did not succeed.
      example:
        code: NOT_FOUND
        message: Not found.
        documentationUrl: https://developer.folk.app/api-reference/errors#not-found
    User:
      type: object
      properties:
        id:
          type: string
        fullName:
          type: string
        email:
          type: string
      required:
        - id
        - fullName
        - email
      description: A user in the workspace.
      example:
        id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
        fullName: John Doe
        email: john.doe@example.com
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: TOO_MANY_REQUESTS
            message:
              type: string
              example: You have exceeded your rate limit.
            documentationUrl:
              type: string
              format: uri
              example: https://developer.folk.app/api-reference/errors#rate-limiting
            requestId:
              type: string
              format: uuid
              example: 123e4567-e89b-12d3-a456-426614174000
            timestamp:
              type: string
              format: date-time
              example: '2025-10-01T12:00:00Z'
            details:
              type: object
              additionalProperties: true
              example:
                policy: burst
                limit: 20
                remaining: 0
                windowSeconds: 2
                retryAfter: '2025-10-01T12:00:02.000Z'
          required:
            - code
            - message
            - documentationUrl
            - requestId
            - timestamp
      required:
        - error
      description: Error response containing error details.
    RateLimitError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: TOO_MANY_REQUESTS
            message:
              type: string
              example: You have exceeded your rate limit.
            documentationUrl:
              type: string
              format: uri
              example: https://developer.folk.app/api-reference/errors#rate-limiting
            requestId:
              type: string
              format: uuid
              example: 123e4567-e89b-12d3-a456-426614174000
            timestamp:
              type: string
              format: date-time
              example: '2025-10-01T12:00:00Z'
            details:
              type: object
              properties:
                policy:
                  type: string
                  enum:
                    - default
                    - burst
                  description: The name of the rate limit policy.
                limit:
                  type: integer
                  description: The maximum number of requests allowed per window.
                remaining:
                  type: integer
                  description: The number of requests remaining in the current window.
                windowSeconds:
                  type: integer
                  description: The length of the window, in seconds.
                retryAfter:
                  type: string
                  format: date-time
                  description: When the current window resets.
                policies:
                  type: array
                  items:
                    type: object
                    properties:
                      policy:
                        type: string
                        enum:
                          - default
                          - burst
                        description: The name of the rate limit policy.
                      limit:
                        type: integer
                        description: The maximum number of requests allowed per window.
                      remaining:
                        type: integer
                        description: >-
                          The number of requests remaining in the current
                          window.
                      windowSeconds:
                        type: integer
                        description: The length of the window, in seconds.
                      retryAfter:
                        type: string
                        format: date-time
                        description: When the current window resets.
                    required:
                      - policy
                      - limit
                      - remaining
                      - windowSeconds
                      - retryAfter
                  description: >-
                    The status of every rate limit policy applied to the
                    request.
              required:
                - policy
                - limit
                - remaining
                - windowSeconds
                - retryAfter
                - policies
              description: >-
                The exceeded rate limit policy. When several are exceeded, the
                one resetting last.
          required:
            - code
            - message
            - documentationUrl
            - requestId
            - timestamp
            - details
      required:
        - error
      description: Error response returned when a rate limit is exceeded.
  responses:
    BadRequest:
      description: The request was unacceptable, often due to missing an invalid parameter.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_REQUEST
              message: The request was invalid.
              documentationUrl: https://developer.folk.app/api-reference/errors#bad-request
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Unauthorized:
      description: No valid API key provided.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: No valid API key provided.
              documentationUrl: https://developer.folk.app/api-reference/errors#unauthorized
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Forbidden:
      description: The API key doesn’t have permissions to perform the request.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: FORBIDDEN
              message: The API key doesn’t have permissions to perform the request.
              documentationUrl: https://developer.folk.app/api-reference/errors#forbidden
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    NotFound:
      description: The requested resource doesn’t exist.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RESOURCE_NOT_FOUND
              message: The requested resource was not found.
              documentationUrl: https://developer.folk.app/api-reference/errors#not-found
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Conflict:
      description: A request with the same `Idempotency-Key` is still being processed.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: IDEMPOTENCY_REQUEST_IN_PROGRESS
              message: >-
                A request with the same Idempotency-Key is still being
                processed. Retry once it has completed.
              documentationUrl: https://developer.folk.app/api-reference/idempotency#errors
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    UnprocessableEntity:
      description: >-
        The request was unacceptable, often due to missing or invalid
        parameters.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNPROCESSABLE_ENTITY
              message: Invalid query parameters
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#unprocessable-entity
              details:
                issues:
                  - code: too_small
                    minimum: 1
                    type: number
                    inclusive: true
                    exact: false
                    message: Number must be greater than or equal to 1
                    path:
                      - limit
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    TooManyRequests:
      description: >-
        Too many requests hit the API too quickly. We recommend an exponential
        backoff of your requests.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            error:
              code: TOO_MANY_REQUESTS
              message: You have exceeded your rate limit.
              documentationUrl: https://developer.folk.app/api-reference/errors#rate-limiting
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
              details:
                policy: burst
                limit: 20
                remaining: 0
                windowSeconds: 2
                retryAfter: '2025-10-01T12:00:02.000Z'
                policies:
                  - policy: default
                    limit: 600
                    remaining: 412
                    windowSeconds: 60
                    retryAfter: '2025-10-01T12:01:00.000Z'
                  - policy: burst
                    limit: 20
                    remaining: 0
                    windowSeconds: 2
                    retryAfter: '2025-10-01T12:00:02.000Z'
    InternalServerError:
      description: Something went wrong on our end.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_SERVER_ERROR
              message: An internal server error occurred.
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#internal-server-error
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    ServiceUnavailable:
      description: The server is overloaded or down for maintenance.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: SERVICE_UNAVAILABLE
              message: The service is currently unavailable.
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#service-unavailable
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
  securitySchemes:
    bearerApiKeyAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.