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