Start an upload

POST

/conversations/{conversationId}/files

const url = 'https://api.asklucy.eu/v1/conversations/example/files';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"example","content_type":"example","size_bytes":1,"sha256":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.asklucy.eu/v1/conversations/example/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "content_type": "example", "size_bytes": 1, "sha256": "example" }'

Creates the file (status pending) and returns a short-lived URL to PUT the bytes to. Then call …/files/{fileId}/complete; the file is checked (type, size, malware) and becomes ready or rejected.

Authorizations

zitadel

Parameters

Path Parameters

conversationId

required

string

/^conv_[A-Za-z0-9]+$/

Header Parameters

Idempotency-Key

string

<= 255 characters

Any unique string (a UUID works). Retries with the same key return the first result.

Request Body^required

application/json

object

name

required

string

<= 255 characters

content_type

required

string

size_bytes

required

integer

>= 1

sha256

Optional; checked after upload when given.

string

Example ^generated

{
  "name": "example",
  "content_type": "example",
  "size_bytes": 1,
  "sha256": "example"
}

Responses

201

Created

application/json

object

file

required

object

required

string

conversation_id

required

string

name

required

string

content_type

required

string

size_bytes

required

integer

sha256

string | null

source

required

upload: added by a person; generated: written by Lucy; local: attached by Lucy from the person’s computer (a shared folder).

string

Allowed values: upload generated local

role

Why Lucy added the file: output, made for the person (show it as a card unless the answer links it inline), including the copy of a file she wrote or edited on the person’s computer; read, attached so she could read it (no card: its step names it). Null for the person’s uploads.

string | null

Allowed values: output read

local

Where the file is on the person’s computer (source local): the one Lucy read it from, or wrote it to. Null otherwise, and on files attached before 2026-11-04.

object

device_id

required

string

path

required

The virtual path there, <share>/<path inside it>.

string

message_id

For generated files, the answer that wrote it.

string | null

status

required

string

Allowed values: pending processing ready rejected

rejection_reason

string | null

created_by

One of:

object
null

object

required

Zitadel user ID.

string

name

required

string

email

string | null format: email

kind

service is a customer system’s Zitadel service user; agent is a service agent (its ID is the agt_ ID), the author of its runs’ messages.

string

Allowed values: person service agent

created_at

required

string format: date-time

download_url

Only on getFile for ready files; valid a few minutes.

string | null format: uri

download_url_expires_at

string | null format: date-time

thumbnail_url

A JPEG preview about 320 px on its long side: the image (a GIF’s first frame) or a PDF’s first page. On getFile and listFiles for ready PNG, JPEG, GIF, WebP and PDF files; null for other files and when none could be made. Valid as long as download_url; fetching it isn’t audited as a download. Always null in file.created events: fetch the file for it. An upload’s is there when it becomes ready, a generated file’s when file.created is sent.

string | null format: uri

thumbnail_url_expires_at

string | null format: date-time

preview_url

A PDF of a Word or PowerPoint file (also the OpenDocument and older kinds, RTF), to read it in the chat with a PDF viewer. On getFile and listFiles for ready files of those types once the conversion has been done (a minute or so after the file is ready); null for other files, while it is pending and when the file could not be converted. Spreadsheets get none (show them from download_url). Valid as long as download_url; fetching it isn’t audited as a download. Never in file.created events.

string | null format: uri

preview_url_expires_at

string | null format: date-time

upload

required

object

url

required

string format: uri

method

required

Allowed value: PUT

headers

required

Send these headers with the PUT.

object

key

additional properties

string

expires_at

required

string format: date-time

Example

{
  "file": {
    "id": "file_4kVt9s",
    "content_type": "application/pdf",
    "source": "upload",
    "role": "output",
    "local": {
      "path": "Documents/product-list.md"
    },
    "status": "pending",
    "rejection_reason": "malware",
    "created_by": {
      "kind": "person"
    }
  },
  "upload": {
    "method": "PUT"
  }
}

400

The request is invalid; errors lists what’s wrong.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

401

Missing, expired or invalid token.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

404

No such object in your organization.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

413

Over the organization’s file size limit (see Me.entitlements).

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

429

Rate limit (problem type …/errors/rate-limited, retry after Retry-After) or quota used up (…/errors/quota-exceeded, with quota saying which limit and when it resets).

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

Retry-After

integer

Seconds to wait before retrying.

Start an upload

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Example generated

Responses

201

Example

400

Example

Headers

401

Example

Headers

404

Example

Headers

413

Example

Headers

429

Example

Headers

Request Body^required

Example ^generated