> ## 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.
# (Beta) List past interactions
> Retrieves paginated past interactions linked to a person, company, or object.
This endpoint is currently in closed beta.
If you'd like access, please contact us at [support@folk.app](mailto:support@folk.app).
## OpenAPI
````yaml /schemas/2025-06-09.json get /v1/interactions/past
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: Deals
description: Operations related to deals.
- name: Groups
description: Operations related to groups.
- 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/interactions/past:
get:
tags:
- Interactions
summary: List past interactions
description: >-
Retrieves paginated past interactions linked to a person, company, or
object.
This endpoint is currently in closed beta.
If
you'd like access, please contact us at
[support@folk.app](mailto:support@folk.app).
operationId: listPastInteractions
parameters:
- schema:
type: string
maxLength: 512
required: false
description: >-
A cursor for pagination across multiple pages of results. Don’t
include this parameter on the first call. Use the
`pagination.nextLink` value returned in a previous response to
request subsequent results.
example: eyJvZmZzZXQiOjN9
name: cursor
in: query
- schema:
type: string
minLength: 40
maxLength: 40
required: true
description: The person, company, or object linked to interactions.
example: per_55175e81-9a52-4ac3-930e-82792c23499b
name: entity.id
in: query
responses:
'200':
description: A paginated list of past interactions with optional pagination link.
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'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Interaction'
pagination:
type: object
properties:
nextLink:
type: string
required:
- items
- pagination
example:
items:
- id: lit_b049db09-c03d-4f32-96d6-d314760add5d
interactionType: logged
from:
type: user
value: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
name: John Doe
to:
type: person
value: per_55175e81-9a52-4ac3-930e-82792c23499b
name: John Doe
entity:
id: per_55175e81-9a52-4ac3-930e-82792c23499b
entityType: person
fullName: John Doe
dateTime: '2025-07-17T09:00:00.000Z'
privacyLevel: sharedFull
title: Coffee with John Doe
content: |-
Had a coffee with John Doe
Discussed the new project.
type: coffee
activityType: coffee
pagination:
nextLink: >-
https://api.folk.app/v1/interactions/past?entity.id=per_55175e81-9a52-4ac3-930e-82792c23499b&cursor=eyJmb28iOiJiYXIifQ%3D%3D
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
data:
items:
- id: lit_b049db09-c03d-4f32-96d6-d314760add5d
interactionType: logged
from:
type: user
value: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
name: John Doe
to:
type: person
value: per_55175e81-9a52-4ac3-930e-82792c23499b
name: John Doe
entity:
id: per_55175e81-9a52-4ac3-930e-82792c23499b
entityType: person
fullName: John Doe
dateTime: '2025-07-17T09:00:00.000Z'
privacyLevel: sharedFull
title: Coffee with John Doe
content: |-
Had a coffee with John Doe
Discussed the new project.
type: coffee
activityType: coffee
pagination:
nextLink: >-
https://api.folk.app/v1/interactions/past?entity.id=per_55175e81-9a52-4ac3-930e-82792c23499b&cursor=eyJmb28iOiJiYXIifQ%3D%3D
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'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.
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:
Interaction:
anyOf:
- $ref: '#/components/schemas/EmailMessageInteraction'
- $ref: '#/components/schemas/CalendarEventInteraction'
- $ref: '#/components/schemas/WhatsappMessageInteraction'
- $ref: '#/components/schemas/LoggedInteraction'
description: >-
An interaction linked to an entity. Can be imported (email, calendar,
WhatsApp) or manually logged.
example:
id: lit_b049db09-c03d-4f32-96d6-d314760add5d
interactionType: logged
from:
type: user
value: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
name: John Doe
to:
type: person
value: per_55175e81-9a52-4ac3-930e-82792c23499b
name: John Doe
entity:
id: per_55175e81-9a52-4ac3-930e-82792c23499b
entityType: person
fullName: John Doe
dateTime: '2025-07-17T09:00:00.000Z'
privacyLevel: sharedFull
title: Coffee with John Doe
content: |-
Had a coffee with John Doe
Discussed the new project.
type: coffee
activityType: coffee
EmailMessageInteraction:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 512
entity:
type: object
properties:
entityType:
type: string
enum:
- person
- company
description: >-
The type of the entity connected to the interaction. Can be
`person` or `company`.
example: person
id:
type: string
minLength: 40
maxLength: 40
description: The ID of the entity connected to the interaction.
example: per_55175e81-9a52-4ac3-930e-82792c23499b
fullName:
type: string
description: The full name of the entity connected to the interaction.
example: John Doe
required:
- entityType
- id
- fullName
description: The entity connected to the interaction.
dateTime:
type: string
format: date-time
description: The date and time of the interaction.
example: '2025-07-17T09:00:00.000Z'
url:
type:
- string
- 'null'
format: uri
description: >-
A link to open the interaction in the original source, when
available.
example: https://mail.google.com/mail/u/0/#inbox/abc123
privacyLevel:
type: string
enum:
- sharedFull
- subjectOnly
- sensitive
- internal
description: >
Interaction privacy level:
- `**sharedFull` means the interaction content is fully visible to
every workspace member.
- `**subjectOnly` means the interacton content is hidden for other
workspace members.
- `**sensitve`/`internal` means the interaction is visible only to
the workspace members involved in the conversation.
For more information about interaction privacy, see our [help center
article](https://help.folk.app/en/articles/13056598-security-internal-and-sensitive-interactions)
example: sharedFull
interactionType:
type: string
enum:
- email
description: The interaction is an imported email message.
example: email
from:
type: object
properties:
type:
type: string
enum:
- email
value:
type: string
description: The email address of the participant.
example: jane@example.com
name:
type: string
description: The display name of the participant.
example: Jane Doe
required:
- type
- value
to:
type: array
items:
type: object
properties:
type:
type: string
enum:
- email
value:
type: string
description: The email address of the participant.
example: jane@example.com
name:
type: string
description: The display name of the participant.
example: Jane Doe
required:
- type
- value
description: The recipients of the email.
content:
type: object
properties:
subject:
type: string
description: The subject of the email or calendar event.
example: Project kickoff
snippet:
type: string
description: >-
A short preview of the interaction content. Omitted when privacy
rules restrict content.
example: Looking forward to discussing the roadmap.
location:
type: string
description: The location of the calendar event, when available.
example: Conference room A
body:
type: string
description: >-
The full body of the email or calendar event. Only returned by
the get interaction endpoint.
example: |-
Hi team,
Looking forward to our kickoff meeting.
required:
- subject
required:
- id
- entity
- dateTime
- url
- privacyLevel
- interactionType
- from
- to
- content
description: An imported email message linked to an entity.
example:
id: b049db09-c03d-4f32-96d6-d314760add5d@gmail.com
interactionType: email
entity:
id: per_55175e81-9a52-4ac3-930e-82792c23499b
entityType: person
fullName: John Doe
dateTime: '2025-07-17T09:00:00.000Z'
url: https://mail.google.com/mail/u/0/#inbox/abc123
privacyLevel: sharedFull
from:
type: email
value: jane@example.com
name: Jane Doe
to:
- type: email
value: john@example.com
name: John Doe
content:
subject: Project kickoff
snippet: Looking forward to discussing the roadmap.
CalendarEventInteraction:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 512
entity:
type: object
properties:
entityType:
type: string
enum:
- person
- company
description: >-
The type of the entity connected to the interaction. Can be
`person` or `company`.
example: person
id:
type: string
minLength: 40
maxLength: 40
description: The ID of the entity connected to the interaction.
example: per_55175e81-9a52-4ac3-930e-82792c23499b
fullName:
type: string
description: The full name of the entity connected to the interaction.
example: John Doe
required:
- entityType
- id
- fullName
description: The entity connected to the interaction.
dateTime:
type: string
format: date-time
description: The date and time of the interaction.
example: '2025-07-17T09:00:00.000Z'
url:
type:
- string
- 'null'
format: uri
description: >-
A link to open the interaction in the original source, when
available.
example: https://mail.google.com/mail/u/0/#inbox/abc123
privacyLevel:
type: string
enum:
- sharedFull
- subjectOnly
- sensitive
- internal
description: >
Interaction privacy level:
- `**sharedFull` means the interaction content is fully visible to
every workspace member.
- `**subjectOnly` means the interacton content is hidden for other
workspace members.
- `**sensitve`/`internal` means the interaction is visible only to
the workspace members involved in the conversation.
For more information about interaction privacy, see our [help center
article](https://help.folk.app/en/articles/13056598-security-internal-and-sensitive-interactions)
example: sharedFull
interactionType:
type: string
enum:
- calendar
description: The interaction is an imported calendar event.
example: calendar
from:
type: object
properties:
type:
type: string
enum:
- email
value:
type: string
description: The email address of the participant.
example: jane@example.com
name:
type: string
description: The display name of the participant.
example: Jane Doe
required:
- type
- value
to:
type: array
items:
type: object
properties:
type:
type: string
enum:
- email
value:
type: string
description: The email address of the participant.
example: jane@example.com
name:
type: string
description: The display name of the participant.
example: Jane Doe
required:
- type
- value
description: The attendees of the calendar event.
content:
type: object
properties:
subject:
type: string
description: The subject of the email or calendar event.
example: Project kickoff
snippet:
type: string
description: >-
A short preview of the interaction content. Omitted when privacy
rules restrict content.
example: Looking forward to discussing the roadmap.
location:
type: string
description: The location of the calendar event, when available.
example: Conference room A
body:
type: string
description: >-
The full body of the email or calendar event. Only returned by
the get interaction endpoint.
example: |-
Hi team,
Looking forward to our kickoff meeting.
required:
- subject
required:
- id
- entity
- dateTime
- url
- privacyLevel
- interactionType
- from
- to
- content
description: An imported calendar event linked to an entity.
example:
id: c149db09-c03d-4f32-96d6-d314760add5e@gmail.com
interactionType: calendar
entity:
id: per_55175e81-9a52-4ac3-930e-82792c23499b
entityType: person
fullName: John Doe
dateTime: '2025-07-18T14:00:00.000Z'
url: https://calendar.google.com/event?eid=abc123
privacyLevel: sharedFull
from:
type: email
value: jane@example.com
name: Jane Doe
to:
- type: email
value: john@example.com
name: John Doe
content:
subject: Weekly sync
location: Conference room A
WhatsappMessageInteraction:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 512
entity:
type: object
properties:
entityType:
type: string
enum:
- person
- company
description: >-
The type of the entity connected to the interaction. Can be
`person` or `company`.
example: person
id:
type: string
minLength: 40
maxLength: 40
description: The ID of the entity connected to the interaction.
example: per_55175e81-9a52-4ac3-930e-82792c23499b
fullName:
type: string
description: The full name of the entity connected to the interaction.
example: John Doe
required:
- entityType
- id
- fullName
description: The entity connected to the interaction.
dateTime:
type: string
format: date-time
description: The date and time of the interaction.
example: '2025-07-17T09:00:00.000Z'
url:
type:
- string
- 'null'
format: uri
description: >-
A link to open the interaction in the original source, when
available.
example: https://mail.google.com/mail/u/0/#inbox/abc123
privacyLevel:
type: string
enum:
- sharedFull
- subjectOnly
- sensitive
- internal
description: >
Interaction privacy level:
- `**sharedFull` means the interaction content is fully visible to
every workspace member.
- `**subjectOnly` means the interacton content is hidden for other
workspace members.
- `**sensitve`/`internal` means the interaction is visible only to
the workspace members involved in the conversation.
For more information about interaction privacy, see our [help center
article](https://help.folk.app/en/articles/13056598-security-internal-and-sensitive-interactions)
example: sharedFull
interactionType:
type: string
enum:
- whatsapp
description: The interaction is an imported WhatsApp message.
example: whatsapp
from:
type: object
properties:
type:
type: string
enum:
- phone
value:
type: string
description: The phone number of the participant.
example: '+14155552671'
name:
type: string
description: The display name of the participant.
example: Jane Doe
required:
- type
- value
to:
type: array
items:
type: object
properties:
type:
type: string
enum:
- phone
value:
type: string
description: The phone number of the participant.
example: '+14155552671'
name:
type: string
description: The display name of the participant.
example: Jane Doe
required:
- type
- value
description: The recipients of the WhatsApp message.
content:
type: object
properties:
text:
type: string
description: The message text. Omitted when privacy rules restrict content.
example: Are we still on for tomorrow?
context:
type: string
description: >-
Additional context around the message. Omitted when privacy
rules restrict content.
example: ''
required:
- id
- entity
- dateTime
- url
- privacyLevel
- interactionType
- from
- to
- content
description: An imported WhatsApp message linked to an entity.
example:
id: d249db09-c03d-4f32-96d6-d314760add5f@whatsapp.com
interactionType: whatsapp
entity:
id: per_55175e81-9a52-4ac3-930e-82792c23499b
entityType: person
fullName: John Doe
dateTime: '2025-07-17T10:30:00.000Z'
url: null
privacyLevel: sensitive
from:
type: phone
value: '+14155552671'
name: Jane Doe
to:
- type: phone
value: '+14155559876'
name: John Doe
content:
text: Are we still on for tomorrow?
LoggedInteraction:
type: object
properties:
id:
type: string
interactionType:
type: string
enum:
- logged
description: The interaction is a manually logged interaction.
example: logged
from:
oneOf:
- type: object
properties:
type:
type: string
enum:
- user
description: The interaction was logged by a workspace member.
example: user
value:
type: string
name:
type: string
description: The display name of the user.
example: John Doe
required:
- type
- value
- type: object
properties:
type:
type: string
enum:
- sender
description: >-
The interaction was logged on behalf of an email sender,
such as a campaign message.
example: sender
name:
type: string
description: The display name of the sender.
example: Jane Doe
value:
type: string
description: The email address of the sender.
example: jane@example.com
required:
- type
- name
- value
description: >-
Who logged the interaction. Can be a workspace user or an email
sender.
to:
type: object
properties:
type:
anyOf:
- type: string
enum:
- person
- type: string
enum:
- company
description: The type of the entity the interaction is linked to.
example: person
value:
type: string
minLength: 40
maxLength: 40
description: The ID of the person or company the interaction is linked to.
example: per_55175e81-9a52-4ac3-930e-82792c23499b
name:
type: string
description: The full name of the linked entity.
example: John Doe
required:
- type
- value
description: The entity the interaction is linked to.
entity:
type: object
properties:
entityType:
type: string
enum:
- person
- company
description: >-
The type of the entity connected to the interaction. Can be
`person` or `company`.
example: person
id:
type: string
minLength: 40
maxLength: 40
description: The ID of the entity connected to the interaction.
example: per_55175e81-9a52-4ac3-930e-82792c23499b
fullName:
type: string
description: The full name of the entity connected to the interaction.
example: John Doe
required:
- entityType
- id
- fullName
description: The entity connected to the interaction.
dateTime:
type: string
format: date-time
description: The date and time of the interaction.
example: '2025-07-17T09:00:00.000Z'
title:
type: string
description: The title of the interaction.
example: Coffee with John Doe
content:
type: string
description: The multi-line content of the interaction.
example: |-
Had a coffee with John Doe
Discussed the new project.
privacyLevel:
type: string
enum:
- sharedFull
description: Logged interactions always expose their content to authorized users.
example: sharedFull
type:
anyOf:
- type: string
maxLength: 50
format: emoji
description: An emoji representing the interaction type.
example: ☕️
- type: string
enum:
- call
- meeting
- message
- coffee
- lunch
- event
- drink
description: A predefined interaction type.
example: coffee
- type: string
enum:
- whatsapp
- twitter
- linkedin
- hangout
- skype
- slack
- iMessage
- fbMessenger
- signal
- discord
- wechat
- telegram
- viber
description: A messaging app used for the interaction.
example: slack
- type: string
enum:
- campaignMessage
description: A campaign message sent via folk.
example: campaignMessage
description: Deprecated. Use `activityType` instead.
deprecated: true
example: coffee
activityType:
anyOf:
- type: string
maxLength: 50
format: emoji
description: An emoji representing the interaction type.
example: ☕️
- type: string
enum:
- call
- meeting
- message
- coffee
- lunch
- event
- drink
description: A predefined interaction type.
example: coffee
- type: string
enum:
- whatsapp
- twitter
- linkedin
- hangout
- skype
- slack
- iMessage
- fbMessenger
- signal
- discord
- wechat
- telegram
- viber
description: A messaging app used for the interaction.
example: slack
- type: string
enum:
- campaignMessage
description: A campaign message sent via folk.
example: campaignMessage
description: >-
The logged activity type. Can be a predefined activity, a messaging
app, or an emoji.
example: coffee
required:
- id
- interactionType
- from
- to
- entity
- dateTime
- title
- content
- privacyLevel
- type
- activityType
description: A manually logged interaction linked to an entity.
example:
id: lit_b049db09-c03d-4f32-96d6-d314760add5d
interactionType: logged
from:
type: user
value: usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c
name: John Doe
to:
type: person
value: per_55175e81-9a52-4ac3-930e-82792c23499b
name: John Doe
title: Coffee with John Doe
content: |-
Had a coffee with John Doe
Discussed the new project.
entity:
id: per_55175e81-9a52-4ac3-930e-82792c23499b
entityType: person
fullName: John Doe
dateTime: '2025-07-17T09:00:00.000Z'
privacyLevel: sharedFull
type: coffee
activityType: coffee
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: RATE_LIMIT_EXCEEDED
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:
limit: 1000
remaining: 0
retryAfter: '2025-10-01T12:00:00Z'
required:
- code
- message
- documentationUrl
- requestId
- timestamp
required:
- error
description: Error response containing error details.
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'
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'
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'
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'
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'
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'
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'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: RATE_LIMIT_EXCEEDED
message: The rate limit has been exceeded.
documentationUrl: https://developer.folk.app/api-reference/errors#rate-limiting
requestId: 123e4567-e89b-12d3-a456-426614174000
timestamp: '2025-10-01T12:00:00Z'
details:
limit: 1000
remaining: 0
retryAfter: '2025-10-01T12:00:00Z'
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
````