Upload a file

POST

/files

curl --request POST \
  --url https://firma.company-gpt.com/companygpt/rag/api/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@file \
  --form collectionId=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --form metadata=example

• CompanyGPT instance

Upload a new file to a collection. The file will be queued for indexing. Only the collection owner or a collection admin may upload.

Request Body: multipart/form-data

• file (required): The file to upload (binary)
• collectionId (required): Target collection UUID
• metadata (optional): JSON-encoded object merged into the file’s source metadata

Authorizations

• BearerAuth

Request Body^required

Media typemultipart/form-data

File upload request (multipart/form-data)

object

file

required

File to upload

string format: binary

collectionId

required

Target collection ID. Required — uploads with no collection are rejected (400).

string format: uuid

metadata

Optional JSON-encoded object merged into the file’s source metadata (e.g. custom ACL fields)

string

Responses

201

File uploaded and an index job queued

Media typeapplication/json

Response for POST /files (handlers.UploadResponse)

object

file

required

File metadata (mirrors handlers.FileInfo)

object

id

required

Unique file identifier

string format: uuid

name

required

Original file name

string

blobPath

required

Path in blob storage

string

sizeBytes

File size in bytes

integer format: int64

nullable

contentType

MIME type

string

nullable

status

required

File processing status

string

Allowed values: pending indexed indexed_with_warning failed

collectionId

Associated collection ID

string format: uuid

nullable

collectionName

Associated collection name

string

nullable

createdAt

required

ISO 8601 creation timestamp

string format: date-time

updatedAt

required

ISO 8601 last update timestamp

string format: date-time

lastIndexedAt

ISO 8601 last indexing timestamp

string format: date-time

nullable

sourceMetadata

Source-specific metadata (ACL fields, SharePoint item info, etc.); omitted/empty for files with no metadata

object

key

additional properties

any

jobId

required

ID of the indexing job queued for this upload

string format: uuid

Example

{
  "file": {
    "status": "pending"
  }
}

400

Invalid request (missing file, missing/invalid collectionId, invalid metadata JSON)

Media typeapplication/json

object

error

required

Error message

string

Example^generated

{
  "error": "example"
}

401

Unauthorized

Media typeapplication/json

object

error

required

Error message

string

Example^generated

{
  "error": "example"
}

404

Collection not found or caller lacks write access (404 used instead of 403 to avoid revealing collection existence)

Media typeapplication/json

object

error

required

Error message

string

Example^generated

{
  "error": "example"
}

413

File too large

Media typeapplication/json

object

error

required

Error message

string

Example^generated

{
  "error": "example"
}