Upload a file

curl --request POST \
  --url https://api.poelis.com/v1/public/files/{target_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=<string>'

{
  "content_type": "application/pdf",
  "deleted": false,
  "description": "Specification document for compressor performance and operating constraints.",
  "id": "990e8400-e29b-41d4-a716-446655440000",
  "originalFileName": "compressor-spec-v3.pdf",
  "size_bytes": 245612,
  "uploadedBy": {
    "id": "auth0|550e8400-e29b-41d4-a716-446655440000",
    "imageUrl": "https://example.com/avatar.png",
    "userName": "Jane Doe"
  },
  "uploaded_at": "2026-04-01T10:11:12.123Z",
  "used_in": [
    {
      "file_link_id": "890e8400-e29b-41d4-a716-446655440000",
      "product_id": "660e8400-e29b-41d4-a716-446655440000",
      "target_id": "770e8400-e29b-41d4-a716-446655440000",
      "target_type": "item"
    }
  ],
  "userTitle": "Compressor specification"
}

Files

Upload a file

Attach a file to a target identified by target_id.

Today the supported targets are items and properties. The API auto-detects the kind of target from the UUID.

Request

Multipart form data:

file (required): the file bytes.
userTitle (optional): editable display title; defaults to the filename.
allow_duplicate (optional, default false): when false, an upload whose (size, content_type) already exists in the workspace returns 409 duplicate_file. Set true to override.

Response

201 Created with the new file. used_in[0] reflects the new link:

target_type="item" for an item target (property_type is null).
target_type="property" for a property target with property_type auto-detected as one of numeric, formula, matrix, text, date, status.

AI description

When AI usage is enabled for the workspace’s organization, Poelis enqueues an AI description generation which runs asynchronously after 201 Created. It is not blocking the upload response. If AI usage is disabled for the organization, no description is generated. Setting description via PATCH /files/{file_id} dismisses further automatic generation for that file.

Errors

400 invalid_request — missing or empty file.
400 file_too_large — file exceeds the configured size limit.
403 — API key org does not match the target’s workspace org.
404 target_not_found — target_id is neither a known item nor a known property.
409 duplicate_file — duplicate exists; retry with allow_duplicate=true to bypass.

POST

public

files

{target_id}

Upload a file

curl --request POST \
  --url https://api.poelis.com/v1/public/files/{target_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=<string>'

{
  "content_type": "application/pdf",
  "deleted": false,
  "description": "Specification document for compressor performance and operating constraints.",
  "id": "990e8400-e29b-41d4-a716-446655440000",
  "originalFileName": "compressor-spec-v3.pdf",
  "size_bytes": 245612,
  "uploadedBy": {
    "id": "auth0|550e8400-e29b-41d4-a716-446655440000",
    "imageUrl": "https://example.com/avatar.png",
    "userName": "Jane Doe"
  },
  "uploaded_at": "2026-04-01T10:11:12.123Z",
  "used_in": [
    {
      "file_link_id": "890e8400-e29b-41d4-a716-446655440000",
      "product_id": "660e8400-e29b-41d4-a716-446655440000",
      "target_id": "770e8400-e29b-41d4-a716-446655440000",
      "target_type": "item"
    }
  ],
  "userTitle": "Compressor specification"
}

Authorizations

Authorization

string

header

required

Enter your API key. Example: Bearer poelis_api_...

Path Parameters

target_id

string

required

Body

multipart/form-data

file

string

required

File to upload.

userTitle

string | null

Optional editable display title for the uploaded file.

allow_duplicate

boolean

default:false

When true, bypass the duplicate-file check (same size and MIME in the workspace).

Response

The newly created file and its initial link usage.

Public representation of a stored file.

string

required

File ID

originalFileName

string

required

Original file name

deleted

boolean

required

Whether the file is soft-deleted

userTitle

string | null

Optional editable file title

content_type

string | null

MIME type

description

string | null

File description

size_bytes

integer | null

File size in bytes

uploadedAt

string | null

ISO 8601 upload timestamp

uploadedBy

PublicUser · object

User who uploaded the file

Show child attributes

Example:

{
  "id": "auth0|550e8400-e29b-41d4-a716-446655440000",
  "imageUrl": "https://example.com/avatar.png",
  "userName": "Jane Doe"
}

used_in

PublicFileUsage · object[]

Current file link placements for this file

Show child attributes

Update file metadata Download file by ID

Documentation Index

Authorizations

Path Parameters

Body

Response