Get a file

GET

/conversations/{conversationId}/files/{fileId}

const url = 'https://api.asklucy.eu/v1/conversations/example/files/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

curl --request GET \
  --url https://api.asklucy.eu/v1/conversations/example/files/example \
  --header 'Authorization: Bearer <token>'

Metadata, plus a short-lived download_url once the file is ready. Each download is recorded in the audit log.

Authorizations

zitadel

Parameters

Path Parameters

conversationId

required

string

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

fileId

required

string

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

Responses

200

application/json

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

Example

{
  "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"
  }
}

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.