--- title: "Automate File Management with the Pigment API" slug: "manage-files-with-the-pigment-api" description: "Learn how to use the Pigment File Storage API to list, upload, and download files programmatically, including permissions, limits, and errors." tags: ["Pigment API", "File Management", "File Storage", "Files", "Workspace Usage"] updated: 2026-09-09T13:38:08Z published: 2026-09-09T13:38:08Z canonical: "kb.pigment.com/manage-files-with-the-pigment-api" stale: true --- > ## Documentation Index > Fetch the complete documentation index at: https://kb.pigment.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](/v1/docs/manage-api-keys). - **Application ID**. This ID represents the Application containing the files. All `File Storage` endpoints are scoped to a single Application. > [!WARNING] > **⚠️ Important** > > Files in Pigment are stored per Application not per Block. For more information, see [Manage file storage limits](/v1/docs/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](/v1/docs/manage-api-keys). ## Swagger / OpenAPI specification Pigment has a Swagger page with all the publicly available API endpoints: [https://pigment.app/api/swagger](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. > [!WARNING] > **⚠️ Important** > > Each page can contain a maximum of 1000 files. ### API response ```json {  "items": [    {      "organizationId": "a1c04dfe-1f42-4a0e-9d31-5b7c1e8f2a44",      "applicationId": "33d0d7d0-6125-47c4-b36a-882f4ed53b33",      "id": "f2b03cab-ba63-4525-bd59-c597f6721973",      "displayFilename": "Invoice Q3 2026.pdf",      "sizeBytes": 248311,      "mimeType": "application/pdf",      "contentType": "pdf",      "uploadedBy": "7c1e5b93-2a44-4d31-9f0e-1f42a1c04dfe",      "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: ```bash # 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}` > [!WARNING] > **⚠️ 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. - 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](/v1/docs/manage-files-with-the-pigment-api#before-you-begin). > [!WARNING] > **⚠️ 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. ```json {  "organizationId": "a1c04dfe-1f42-4a0e-9d31-5b7c1e8f2a44",  "applicationId": "33d0d7d0-6125-47c4-b36a-882f4ed53b33",  "id": "f2b03cab-ba63-4525-bd59-c597f6721973",  "displayFilename": "Invoice Q3 2026.pdf",  "contentType": "pdf",  "mimeType": "application/pdf",  "sizeBytes": 248311,  "uploadedBy": "7c1e5b93-2a44-4d31-9f0e-1f42a1c04dfe",  "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: ```bash # 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}" \ -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](/v1/docs/manage-files-with-the-pigment-api#list-files) endpoint above and `{APPLICATION_ID}` with the ID of the Application containing the file. > [!NOTE] > ℹ️ 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: ```bash # 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 > [!WARNING] > **⚠️ 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. | Limit | Value | | --- | --- | | Upload calls | 100 per hour | | Download calls | 1000 per hour | | Individual file size | 500 MB | | Files per Application | 1000 | | Workspace storage | 10 GB (Essentials), 25 GB (Professional), 50 GB (Enterprise) | 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](https://kb.pigment.com/docs/manage-file-storage-limits). ## Errors | Code | Meaning | | --- | --- | | `400` | Missing or invalid `file` form field, or malformed request body. | | `401` | Missing or invalid API key. | | `403` | Key lacks the Files scope, owner lacks `Read Files` or `Manage Files` permission, the Application does not exist or is not accessible, Workspace storage quota is exhausted, or Application file limit is reached. | | `404` | Unknown file ID, or the file does not belong to the Application. | | `413` | File exceeds the 500 MB size limit. | | `415` | File type not allowed. | | `429` | Rate limit exceeded. | | `500` | Server-side failure during validation or upload, or an unhandled error. | > [!NOTE] > ℹ️ **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**.