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

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.

Upload File

POST /api/v1/files

Uploads a file of up to 3 MB. The request is multipart/form-data:

Images that customers see in the widget, such as material pictures, should be public.

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. Objects that referred to it keep the uuid, but the picture or attachment no longer loads. 204 No Content.

Errors