> ## 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. # Create a view > Create a view in a group: a table view, or a kanban view grouped by a single select field. The settings that aren't sent get the defaults of the entity type and the view type. ## OpenAPI ````yaml /schemas/2025-06-09.json post /v1/views 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: Campaigns description: >- Operations related to campaigns: emails, or sequences of emails, sent to people or companies, and their messages. - name: Companies description: Operations related to companies. - name: Credits description: Operations related to credits. - name: Custom objects description: >- Operations related to objects of any type in a group, such as deals. Every object type shares these endpoints, with its name given as the `objectType` path parameter. - 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: Person enrichments description: Operations related to person enrichments. - name: Reminders description: Operations related to reminders. - name: Tasks description: Operations related to tasks. - name: Users description: Operations related to users. - name: Views description: Operations related to views. - name: Webhooks description: Operations related to webhooks. paths: /v1/views: post: tags: - Views summary: Create a view description: >- Create a view in a group: a table view, or a kanban view grouped by a single select field. The settings that aren't sent get the defaults of the entity type and the view type. operationId: createView parameters: - 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: $ref: '#/components/schemas/CreateViewInput' responses: '200': description: The created view. 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: allOf: - $ref: '#/components/schemas/View' - example: id: viw_3f1c9a2e-0386-434d-82d7-a91eb6badd71 groupId: grp_92ab3f1c-0386-434d-82d7-a91eb6badd71 name: Hot leads entityType: person filter: combinator: and conditions: - field: interactionMetadata.workspace.lastInteractedAt operator: gt value: 30-days-ago visibleFields: - jobTitle - companies - emails position: after: viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71 createdAt: '2025-07-17T09:00:00.000Z' createdBy: id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71 fullName: John Doe email: john.doe@example.com type: table sort: field: interactionMetadata.user.lastInteractedAt direction: desc deprecations: type: array items: type: string example: - This field is deprecated required: - data example: data: id: viw_3f1c9a2e-0386-434d-82d7-a91eb6badd71 groupId: grp_92ab3f1c-0386-434d-82d7-a91eb6badd71 name: Hot leads entityType: person filter: combinator: and conditions: - field: interactionMetadata.workspace.lastInteractedAt operator: gt value: 30-days-ago visibleFields: - jobTitle - companies - emails position: after: viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71 createdAt: '2025-07-17T09:00:00.000Z' createdBy: id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71 fullName: John Doe email: john.doe@example.com type: table sort: field: interactionMetadata.user.lastInteractedAt direction: desc '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: schemas: CreateViewInput: oneOf: - type: object properties: groupId: type: string minLength: 40 maxLength: 40 description: The group the view belongs to. example: grp_92ab3f1c-0386-434d-82d7-a91eb6badd71 name: type: string minLength: 1 maxLength: 500 description: The name of the view, as shown in the app. example: Hot leads entityType: type: string maxLength: 500 description: >- The entity type of the view: `person`, `company`, or the name of an object type of the group. example: person filter: type: - object - 'null' properties: combinator: type: string enum: - and - or description: The logical operator combining the conditions. example: and conditions: type: array items: type: object properties: field: type: string maxLength: 1000 description: >- The field the condition applies to, with the same keys as the filters of the search endpoints, e.g. `jobTitle`, `company.industry` or `customFieldValues..`. example: jobTitle operator: type: string enum: - eq - not_eq - like - not_like - gt - lt - in - all - not_in - empty - not_empty example: like value: anyOf: - type: string maxLength: 500 - type: number - type: array items: type: string maxLength: 500 maxItems: 100 - type: array items: anyOf: - type: object properties: id: type: string maxLength: 64 required: - id additionalProperties: false - type: object properties: email: type: string maxLength: 254 required: - email additionalProperties: false maxItems: 100 description: >- The value of the condition: - a single value for `eq`, `not_eq`, `like`, `not_like`, `gt` and `lt` on text, number and date fields; - a list for `in`, `all` and `not_in`, and for `eq` and `not_eq` on select, user and reference fields, where they mean "exactly these values"; - absent for `empty` and `not_empty`. Numbers are given as a number or a string, select options are given by label, users by `{ id }` or `{ email }`, people, companies and groups by `{ id }`, dates as `YYYY-MM-DD` or relative dates (`today`, `yesterday`, `tomorrow`, `7-days-ago`, `in-3-months`). example: engineer required: - field - operator additionalProperties: false description: A condition of the filter of a view. maxItems: 50 description: >- The conditions of the filter, in order, at most 50. The same field can appear in several conditions. An empty list means no filter. required: - combinator - conditions additionalProperties: false description: >- The filter of the view, `null` or absent for no filter. Unlike the search endpoints, the filter is a list of conditions. visibleFields: type: array items: type: string maxLength: 1000 maxItems: 100 description: >- The fields shown by the view, in display order, with the same keys as the filter, at most 100. The name column is always shown and is never listed. example: - jobTitle - companies - emails position: anyOf: - type: object properties: after: type: - string - 'null' minLength: 40 maxLength: 40 required: - after additionalProperties: false - type: object properties: before: type: - string - 'null' minLength: 40 maxLength: 40 required: - before additionalProperties: false description: >- Where the view goes among the views of its group: `{ "after": }`, `{ "before": }`, `{ "after": null }` for the first position or `{ "before": null }` for the last one. Last by default. example: after: viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71 type: type: string enum: - table sort: type: object properties: field: type: string maxLength: 1000 description: >- The field the view is sorted by, with the same keys as the filter. example: interactionMetadata.user.lastInteractedAt direction: type: string enum: - asc - desc description: Ascending (`asc`) or descending (`desc`). example: desc required: - field - direction additionalProperties: false description: >- The sort of the view. When the sorted field no longer exists, the default sort of the entity type is returned. required: - groupId - name - entityType - type additionalProperties: false - type: object properties: groupId: type: string minLength: 40 maxLength: 40 description: The group the view belongs to. example: grp_92ab3f1c-0386-434d-82d7-a91eb6badd71 name: type: string minLength: 1 maxLength: 500 description: The name of the view, as shown in the app. example: Hot leads entityType: type: string maxLength: 500 description: >- The entity type of the view: `person`, `company`, or the name of an object type of the group. example: person filter: type: - object - 'null' properties: combinator: type: string enum: - and - or description: The logical operator combining the conditions. example: and conditions: type: array items: type: object properties: field: type: string maxLength: 1000 description: >- The field the condition applies to, with the same keys as the filters of the search endpoints, e.g. `jobTitle`, `company.industry` or `customFieldValues..`. example: jobTitle operator: type: string enum: - eq - not_eq - like - not_like - gt - lt - in - all - not_in - empty - not_empty example: like value: anyOf: - type: string maxLength: 500 - type: number - type: array items: type: string maxLength: 500 maxItems: 100 - type: array items: anyOf: - type: object properties: id: type: string maxLength: 64 required: - id additionalProperties: false - type: object properties: email: type: string maxLength: 254 required: - email additionalProperties: false maxItems: 100 description: >- The value of the condition: - a single value for `eq`, `not_eq`, `like`, `not_like`, `gt` and `lt` on text, number and date fields; - a list for `in`, `all` and `not_in`, and for `eq` and `not_eq` on select, user and reference fields, where they mean "exactly these values"; - absent for `empty` and `not_empty`. Numbers are given as a number or a string, select options are given by label, users by `{ id }` or `{ email }`, people, companies and groups by `{ id }`, dates as `YYYY-MM-DD` or relative dates (`today`, `yesterday`, `tomorrow`, `7-days-ago`, `in-3-months`). example: engineer required: - field - operator additionalProperties: false description: A condition of the filter of a view. maxItems: 50 description: >- The conditions of the filter, in order, at most 50. The same field can appear in several conditions. An empty list means no filter. required: - combinator - conditions additionalProperties: false description: >- The filter of the view, `null` or absent for no filter. Unlike the search endpoints, the filter is a list of conditions. visibleFields: type: array items: type: string maxLength: 1000 maxItems: 100 description: >- The fields shown by the view, in display order, with the same keys as the filter, at most 100. The name column is always shown and is never listed. example: - jobTitle - companies - emails position: anyOf: - type: object properties: after: type: - string - 'null' minLength: 40 maxLength: 40 required: - after additionalProperties: false - type: object properties: before: type: - string - 'null' minLength: 40 maxLength: 40 required: - before additionalProperties: false description: >- Where the view goes among the views of its group: `{ "after": }`, `{ "before": }`, `{ "after": null }` for the first position or `{ "before": null }` for the last one. Last by default. example: after: viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71 type: type: string enum: - kanban groupBy: type: string maxLength: 1000 description: The single select field the columns come from. example: customFieldValues.grp_92ab3f1c-0386-434d-82d7-a91eb6badd71.Stage columns: type: array items: type: object properties: option: type: - string - 'null' maxLength: 100 description: >- The label of the option of the `groupBy` field, `null` for the "No value" column. example: Qualified hidden: type: boolean default: false description: Whether the column is hidden. `false` by default. example: false required: - option additionalProperties: false description: A column of a kanban view. maxItems: 1001 description: >- The columns, in display order: every option of the `groupBy` field once, plus `null` for the "No value" column. By default, the options in their order, all visible. required: - groupId - name - entityType - type - groupBy additionalProperties: false description: >- A view of a group. Its settings depend on its `type`: `sort` for table views, `groupBy` and `columns` for kanban views. View: oneOf: - $ref: '#/components/schemas/TableView' - $ref: '#/components/schemas/KanbanView' discriminator: propertyName: type mapping: table: '#/components/schemas/TableView' kanban: '#/components/schemas/KanbanView' description: >- A view of a group. Its settings depend on its `type`: `sort` for table views, `groupBy` and `columns` for kanban views. TableView: type: object properties: id: type: string groupId: type: - string - 'null' description: >- The group the view belongs to, `null` for personal views, which belong to no group. example: grp_92ab3f1c-0386-434d-82d7-a91eb6badd71 name: type: string description: The name of the view, as shown in the app. example: Hot leads entityType: type: string description: >- The entity type of the view: `person`, `company`, or the name of an object type of the group. example: person filter: type: - object - 'null' properties: combinator: type: string enum: - and - or description: The logical operator combining the conditions. example: and conditions: type: array items: type: object properties: field: type: string description: >- The field the condition applies to, with the same keys as the filters of the search endpoints, e.g. `jobTitle`, `company.industry` or `customFieldValues..`. example: jobTitle operator: type: string enum: - eq - not_eq - like - not_like - gt - lt - in - all - not_in - empty - not_empty example: like value: anyOf: - type: string - type: array items: type: string - type: array items: type: object properties: id: type: string required: - id description: >- The value of the condition: - a single value for `eq`, `not_eq`, `like`, `not_like`, `gt` and `lt` on text, number and date fields; - a list for `in`, `all` and `not_in`, and for `eq` and `not_eq` on select, user and reference fields, where they mean "exactly these values"; - absent for `empty` and `not_empty`. Select options are given by label, users, people, companies and groups by `{ id }`, dates as `YYYY-MM-DD` or relative dates (`today`, `yesterday`, `tomorrow`, `7-days-ago`, `in-3-months`). example: engineer required: - field - operator description: A condition of the filter of a view. description: >- The conditions of the filter, in order. The same field can appear in several conditions. required: - combinator - conditions description: >- The filter of the view, `null` when the view has no filter. Unlike the search endpoints, the filter is a list of conditions. visibleFields: type: array items: type: string description: >- The fields shown by the view, in display order, with the same keys as the filter. The name column is always shown and never listed. example: - jobTitle - companies - emails position: type: object properties: after: type: - string - 'null' description: >- The id of the view just before this one in its group, `null` for the first view. example: viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71 required: - after description: >- The position of the view in the list of views of its group, as in the app's sidebar. createdAt: type: string format: date-time description: The date and time the view was created, in ISO format. example: '2025-07-17T09:00:00.000Z' createdBy: allOf: - $ref: '#/components/schemas/User' - type: - object - 'null' description: >- The user who created the view, `null` when it was created by folk. type: type: string enum: - table sort: type: object properties: field: type: string description: >- The field the view is sorted by, with the same keys as the filter. example: interactionMetadata.user.lastInteractedAt direction: type: string enum: - asc - desc description: Ascending (`asc`) or descending (`desc`). example: desc required: - field - direction description: >- The sort of the view. When the sorted field no longer exists, the default sort of the entity type is returned. required: - id - groupId - name - entityType - filter - visibleFields - position - createdAt - createdBy - type - sort description: A view displaying the entities as rows. example: id: viw_3f1c9a2e-0386-434d-82d7-a91eb6badd71 groupId: grp_92ab3f1c-0386-434d-82d7-a91eb6badd71 name: Hot leads entityType: person filter: combinator: and conditions: - field: interactionMetadata.workspace.lastInteractedAt operator: gt value: 30-days-ago visibleFields: - jobTitle - companies - emails position: after: viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71 createdAt: '2025-07-17T09:00:00.000Z' createdBy: id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71 fullName: John Doe email: john.doe@example.com type: table sort: field: interactionMetadata.user.lastInteractedAt direction: desc KanbanView: type: object properties: id: type: string groupId: type: - string - 'null' description: >- The group the view belongs to, `null` for personal views, which belong to no group. example: grp_92ab3f1c-0386-434d-82d7-a91eb6badd71 name: type: string description: The name of the view, as shown in the app. example: Hot leads entityType: type: string description: >- The entity type of the view: `person`, `company`, or the name of an object type of the group. example: person filter: type: - object - 'null' properties: combinator: type: string enum: - and - or description: The logical operator combining the conditions. example: and conditions: type: array items: type: object properties: field: type: string description: >- The field the condition applies to, with the same keys as the filters of the search endpoints, e.g. `jobTitle`, `company.industry` or `customFieldValues..`. example: jobTitle operator: type: string enum: - eq - not_eq - like - not_like - gt - lt - in - all - not_in - empty - not_empty example: like value: anyOf: - type: string - type: array items: type: string - type: array items: type: object properties: id: type: string required: - id description: >- The value of the condition: - a single value for `eq`, `not_eq`, `like`, `not_like`, `gt` and `lt` on text, number and date fields; - a list for `in`, `all` and `not_in`, and for `eq` and `not_eq` on select, user and reference fields, where they mean "exactly these values"; - absent for `empty` and `not_empty`. Select options are given by label, users, people, companies and groups by `{ id }`, dates as `YYYY-MM-DD` or relative dates (`today`, `yesterday`, `tomorrow`, `7-days-ago`, `in-3-months`). example: engineer required: - field - operator description: A condition of the filter of a view. description: >- The conditions of the filter, in order. The same field can appear in several conditions. required: - combinator - conditions description: >- The filter of the view, `null` when the view has no filter. Unlike the search endpoints, the filter is a list of conditions. visibleFields: type: array items: type: string description: >- The fields shown by the view, in display order, with the same keys as the filter. The name column is always shown and never listed. example: - jobTitle - companies - emails position: type: object properties: after: type: - string - 'null' description: >- The id of the view just before this one in its group, `null` for the first view. example: viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71 required: - after description: >- The position of the view in the list of views of its group, as in the app's sidebar. createdAt: type: string format: date-time description: The date and time the view was created, in ISO format. example: '2025-07-17T09:00:00.000Z' createdBy: allOf: - $ref: '#/components/schemas/User' - type: - object - 'null' description: >- The user who created the view, `null` when it was created by folk. type: type: string enum: - kanban groupBy: type: string description: The single select field the columns come from. example: customFieldValues.grp_92ab3f1c-0386-434d-82d7-a91eb6badd71.Stage columns: type: array items: type: object properties: option: type: - string - 'null' description: >- The label of the option of the `groupBy` field, `null` for the "No value" column. example: Qualified hidden: type: boolean description: Whether the column is hidden. example: false required: - option - hidden description: A column of a kanban view. description: >- The columns, in display order: one per option of the `groupBy` field, plus the "No value" column. required: - id - groupId - name - entityType - filter - visibleFields - position - createdAt - createdBy - type - groupBy - columns description: A view displaying the entities as cards, in columns. example: id: viw_8e7d6c5b-0386-434d-82d7-a91eb6badd71 groupId: grp_92ab3f1c-0386-434d-82d7-a91eb6badd71 name: Pipeline entityType: person filter: combinator: and conditions: - field: interactionMetadata.workspace.lastInteractedAt operator: gt value: 30-days-ago visibleFields: - jobTitle - companies - emails position: after: viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71 createdAt: '2025-07-17T09:00:00.000Z' createdBy: id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71 fullName: John Doe email: john.doe@example.com type: kanban groupBy: customFieldValues.grp_92ab3f1c-0386-434d-82d7-a91eb6badd71.Stage columns: - option: Lead hidden: false - option: Qualified hidden: false - option: Lost hidden: true - option: null hidden: false 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. 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 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. 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, or the resource is in a state that does not allow the operation. 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: schema: type: integer example: 5 description: >- When the conflict resolves on its own, the number of seconds to wait before retrying. 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.