OpenAPI Specification
openapi: 3.0.3
info:
title: Folk External Companies Users 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
tags:
- name: Users
description: Operations related to users.
paths:
/v1/users:
get:
security:
- bearerApiKeyAuth: []
operationId: listUsers
summary: List users
description: Returns a list of workspace users.
tags:
- Users
parameters:
- schema:
type: integer
minimum: 1
maximum: 100
default: 20
required: false
description: The number of items to return.
example: 20
name: limit
in: query
- schema:
type: string
maxLength: 128
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
responses:
'200':
description: A paginated list of users in the workspace. The `data.items` field contains the list of users, and the `data.pagination.nextLink` field contains a link to the next page of results, if available.
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/User'
pagination:
type: object
properties:
nextLink:
type: string
required:
- items
- pagination
example:
items:
- id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
fullName: John Doe
email: john.doe@example.com
pagination:
nextLink: https://api.folk.app/v1/users?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
data:
items:
- id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
fullName: John Doe
email: john.doe@example.com
pagination:
nextLink: https://api.folk.app/v1/users?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%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'
/v1/users/me:
get:
security:
- bearerApiKeyAuth: []
operationId: getCurrentUser
summary: Get the current user
description: Returns the current workspace user.
tags:
- Users
responses:
'200':
description: The current user associated with the API key.
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:
$ref: '#/components/schemas/CurrentUser'
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
data:
id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
fullName: John Doe
email: john.doe@example.com
'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'
/v1/users/{userId}:
get:
security:
- bearerApiKeyAuth: []
operationId: getUser
summary: Get a user
description: Returns a workspace user.
tags:
- Users
parameters:
- schema:
type: string
minLength: 40
maxLength: 40
required: true
description: The ID of the user to retrieve.
example: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
name: userId
in: path
responses:
'200':
description: The retrieved user in the workspace.
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:
$ref: '#/components/schemas/User'
deprecations:
type: array
items:
type: string
example:
- This field is deprecated
required:
- data
example:
data:
id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
fullName: John Doe
email: john.doe@example.com
'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'
components:
responses:
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'
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'
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'
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'
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'
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'
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'
schemas:
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
CurrentUser:
type: object
properties:
id:
type: string
fullName:
type: string
email:
type: string
required:
- id
- fullName
- email
description: The current workspace user.
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: 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.
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.
Retry-After:
schema:
type: integer
example: 60
description: The number of seconds to wait before making a new request after hitting the rate limit.
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-Remaining:
schema:
type: integer
example: 998
description: The number of requests remaining in the current rate limit window.
securitySchemes:
bearerApiKeyAuth:
type: http
scheme: bearer
description: API key for authentication