Files
Uploading, listing, downloading and deleting files — personal or project files used as images, logos, attachments and receipt scans.
Files are images and documents stored by Configo: material and configurator pictures, document logos, wiki
attachments, scanned receipts. Other objects refer to a file by its uuid (image_uuid, logo_uuid, file_uuid).
A file is either personal, owned by the user who uploaded it, or a project file, available to every member of the project. A file is either public, readable by anyone with its URL, or private.
Uploads are de-duplicated: uploading the same content again into the same place returns the existing file.
Field types follow the field notation.
Access
Every endpoint on this page requires the files OAuth scope. A user can reach their personal files and the files of
every project they are a member of; no role permission is needed.
File Object
File Structure
| Field | Type | Description |
|---|---|---|
| uuid | uuid | File ID |
| name | string | Original file name |
| mime_type | string | MIME type as sent on upload |
| extension | string | Extension, lower case, up to 16 characters; may be empty |
| size | integer | Size in bytes |
| is_public | boolean | Whether the file can be read without authentication |
| pending_until? | ?ISO8601 datetime | List only: set for a file control upload not yet in a product; it is deleted after this time |
| url | string | Relative URL, /uploads/{uuid}, on https://configo.org |
| created_at | ISO8601 datetime | When the file was uploaded |
Example File
{
"uuid": "0199ae50-0000-7000-8000-000000000001",
"name": "logo.png",
"mime_type": "image/png",
"extension": "png",
"size": 18342,
"is_public": true,
"url": "/uploads/0199ae50-0000-7000-8000-000000000001",
"created_at": "2026-08-14T12:50:00.000Z"
}
Reading file content
url serves the file. A public file can be fetched by anyone. A private file needs either a signed URL from
Get File Download URL, or the browser session of a user with access; an OAuth bearer token
is not accepted on /uploads. Add ?download=1 to get it as an attachment rather than inline.
List Files
GET /api/v1/files
Returns the user's personal files, newest first. With project_uuid, returns that project's files instead.
| Query param | Type | Description |
|---|---|---|
| project_uuid? | uuid | A project the user is a member of |
Upload File
POST /api/v1/files
Uploads a file of up to 3 MB. The request is multipart/form-data:
| Field | Type | Description |
|---|---|---|
| file | file | The file |
| project_uuid? | uuid | Upload as a project file. Default: a personal file |
| is_public? | string | true to make the file public. Default: private |
| pending? | string | true for a file control attachment, see below |
Images that customers see in the widget, such as material pictures, should be public.
With pending=true the file is an attachment for a file control: project_uuid is required, the file is private,
up to 5 MB with an extension from the widget upload list, and is never de-duplicated.
Put its {uuid, name} into a product's configuration; saving the product attaches the file, and an upload no product
refers to within 24 hours is deleted. Otherwise the request fails with 400 REQ_FILE_NOT_ALLOWED.
Example Request
curl https://configo.org/api/v1/files \
-H "Authorization: Bearer $TOKEN" \
-H "User-Agent: ConfigoClient (curl, 8.0)" \
-F [email protected] \
-F project_uuid=0198e7a0-0000-7000-8000-000000000001 \
-F is_public=true
Response
201 Created for a new file, or 200 OK with the existing file if the same content was already uploaded to the same
place:
{
"uuid": "0199ae50-0000-7000-8000-000000000001",
"name": "logo.png",
"size": 18342,
"mime_type": "image/png",
"is_public": true,
"url": "/uploads/0199ae50-0000-7000-8000-000000000001"
}
The response has no extension or created_at. When an existing file is returned, its original name and
is_public are kept, even if they differ from this upload.
Get File
GET /api/v1/files/{file.uuid}
Returns a file.
Get File Download URL
GET /api/v1/files/{file.uuid}/download
Returns a signed URL that downloads the file without authentication for 15 minutes:
{
"url": "/uploads/0199ae50-0000-7000-8000-000000000001?token=eyJhbGciOi...&download=1",
"expires_in": 900
}
expires_in is in seconds.
Delete File
DELETE /api/v1/files/{file.uuid}
Deletes the file and its content. 204 No Content.
A file that is still used as a material or configurator picture, a document template logo, a receipt scan or a
file value of a product is not deleted: the request fails with 409 FILE_IN_USE. Detach it first.
Get Storage Usage
GET /api/v1/files/usage
How much of the file storage is used. Storage belongs to the account that owns the projects: every file of every
project the owner has, plus the owner's personal files, counts against the owner's plan storage and bought storage
packs (see Billing). When it is full, uploads fail with 403 LIMIT_STORAGE_REACHED; existing
files stay. The owner is notified when 80%, 90% and 100% is used.
| Query | Type | Description |
|---|---|---|
| project_uuid? | uuid | Report the storage of this project's owner. Default: your own |
{
"used": 327155712,
"quota": 1073741824
}
Both values are in bytes. quota is 0 when the owner has no active subscription.
Errors
| Status | Code | When |
|---|---|---|
| 400 | REQ_VALIDATION_FAILED |
Upload: no file field, or the file is larger than 3 MB |
| 403 | LIMIT_STORAGE_REACHED |
Upload: the storage of the project owner (or yours, for a personal file) is full |
| 403 | AUTH_INSUFFICIENT_SCOPE |
The token lacks files |
| 404 | RES_NOT_FOUND |
The file does not exist or is not accessible; upload: the project is not accessible |