Automate File Management with the Pigment API

The Pigment API provides endpoints for automating the management of Files in your Workspace. This article explains how to list, upload, and download files programmatically.

Before you begin

To call the Pigment File Storage API, you need the following information.

• Pigment API Key. This private key is used to authenticate the service calling the API. To generate the key, go to Workspace settings and select API Keys. You need the Files scope for all endpoints in this page. For more information, see Manage API Keys.

• Application ID. This ID represents the Application containing the files. All File Storage endpoints are scoped to a single Application.

⚠️ Important

Files in Pigment are stored per Application not per Block. For more information, see Manage file storage limits.

Access and permissions

API keys impersonate the access rights of their owner.

• To upload a file, the key owner must have the Manage Files permission on the target Application.

• To download or list files, the owner needs the Read Files permission.

These are the same permissions applied when working with files in Pigment. For more information, see Manage API keys.

Swagger / OpenAPI specification

Pigment has a Swagger page with all the publicly available API endpoints: https://pigment.app/api/swagger.

The File Storage endpoints are documented under FilesV1.

List files

Use the following GET endpoint to retrieve the files stored in an Application, and resolve the file id needed to download a file:

https://pigment.app/api/v1/files?applicationId={APPLICATION_ID}

Replace {APPLICATION_ID} with the ID of the Application containing your files.

Request configuration

• The applicationId parameter is required and identifies the Application containing the files you want to list.

• The cursor parameter is optional and is used to retrieve the next page of results. Pass the nextCursor value from the previous response.

⚠️ Important

Each page can contain a maximum of 1000 files.

API response

{
  "items": [
    {
      "id": "f2b03cab-ba63-4525-bd59-c597f6721973",
      "name": "Invoice Q3 2026.pdf",
      "sizeBytes": 248311,
      "contentType": "application/pdf",
      "uploadedBy": "john.doe@company.com",
      "uploadedAt": "2026-05-13T10:00:00.000Z"
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjUwfQ",
  "hasMore": true
}

Files are ordered by upload date, with the most recently uploaded files returned first. When hasMore is false and nextCursor is null, this means there are no more pages to retrieve.

Example

cURL example:

# Variables
export PIGMENT_API_KEY="CHANGE ME"
export APPLICATION_ID="CHANGE ME"

# List files
curl -X GET "https://pigment.app/api/v1/files?applicationId=${APPLICATION_ID}" \
-H "Authorization: Bearer ${PIGMENT_API_KEY}"

Upload a file

Use this POST endpoint to upload a single file to an Application:

https://pigment.app/api/v1/files?applicationId={APPLICATION_ID}

⚠️ Important
The file must be sent as multipart/form-data, in a form field named file. The file name is taken from the filename of that part, so there is no separate name parameter.

Request configuration

• Replace {APPLICATION_ID} with the ID of the target Application.

• Send the file in a file form field. Its filename becomes the file name shown in Pigment.

• Set the Content-Type header of the request to multipart/form-data. The media type of the file itself is declared in the form part, for example type=application/pdf.

• To authenticate the API call, add an HTTP Authorization header to your request: Authorization: Bearer {API_KEY}

• Replace {API_KEY} with the key retrieved in Before you begin.

⚠️ Important

Your final URL should look like this:

https://pigment.app/api/v1/files?applicationId=33d0d7d0-6125-47c4-b36a-882f4ed53b33

And the request header like this:

Authorization: Bearer M2pwMmUyMzItOTg3NS00MmY0LTlmY2YtNjNmZTJjZTU2OGpw

API response

Calling the endpoint above returns the metadata of the created file, including the id needed to download it later.

{
  "id": "f2b03cab-ba63-4525-bd59-c597f6721973",
  "organizationId": "a1c04dfe-1f42-4a0e-9d31-5b7c1e8f2a44",
  "applicationId": "33d0d7d0-6125-47c4-b36a-882f4ed53b33",
  "displayFilename": "Invoice Q3 2026.pdf",
  "contentType": "pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 248311,
  "uploadedBy": "john.doe@company.com",
  "uploadedAt": "2026-05-13T10:00:00.000Z"
}

In the response:

• displayFilename is the file name shown in Pigment.

• The file format is returned as both:

  • contentType. This contains the file extension, such as pdf.

  • mimeType. This contains the full media type, such as application/pdf.

Example

cURL example:

# Variables
export PIGMENT_API_KEY="CHANGE ME"
export APPLICATION_ID="CHANGE ME"
export FILE_PATH="CHANGE ME"

# Upload the file
curl -X POST \
"https://pigment.app/api/v1/files?applicationId=${APPLICATION_ID}" \
-H "Authorization: Bearer ${PIGMENT_API_KEY}" \
-H "Content-Type: multipart/form-data" 
-F "file=@/{FILE_PATH};type=application/pdf"

Download a file

Use this GET endpoint to download a single file:

https://pigment.app/api/v1/files/{FILE_ID}/content?applicationId={APPLICATION_ID}

Replace {FILE_ID} with the id retrieved from the List files endpoint above and {APPLICATION_ID} with the ID of the Application containing the file.

ℹ️ Note

Your final URL should look like this:

https://pigment.app/api/v1/files/f2b03cab-ba63-4525-bd59-c597f6721973/content?applicationId=33d0d7d0-6125-47c4-b36a-882f4ed53b33

And the request header like this:

Authorization: Bearer M2pwMmUyMzItOTg3NS00MmY0LTlmY2YtNjNmZTJjZTU2OGpw

API response

The content of the requested file is streamed directly in the response body, with a 200 status code. Use your client's usual mechanism to write the response to disk, for example --output with cURL.

Example

cURL example:

# Variables
export PIGMENT_API_KEY="CHANGE ME"
export APPLICATION_ID="CHANGE ME"
export FILE_ID="CHANGE ME"

# Download the file
curl -X GET \
"https://pigment.app/api/v1/files/${FILE_ID}/content?applicationId=${APPLICATION_ID}" \
-H "Authorization: Bearer ${PIGMENT_API_KEY}" \
--output "downloaded-file.pdf"

Downloading several files

The File Storage API processes one file per request. To download multiple files, use the List files endpoint to retrieve their IDs, then send a Download a file request for each file.

Limits

⚠️ Important

Retrieving close to 1000 files from an Application can consume most of the hourly read request limit.

Consider the rate limits in the following table when sending requests in a loop.

Rate limits apply at Workspace level, so several API keys in the same Workspace draw on the same budget. Exceeding a limit returns a 429 error.

The upload and download rate limits are defined by organization settings and can be adjusted by Pigment Support on request. The individual file size, files per Application and Workspace storage limits are fixed and associated with your plan.

For details quotas and usage limits, see Manage file storage limits.

Errors

ℹ️ Note

A 403 covers several distinct cases. Use the error field in the response body rather than the status code alone to tell a permission problem from a storage quota or file limit problem.

Troubleshooting

In addition to the API responses above, you can check file activity in the History of the Application. API operations appear alongside operations performed from the interface.

If an upload fails, check whether the Application has reached the 1000-file limit or the Workspace has reached its storage quota, both visible in Plan & Usage.