List my conversations

GET

/conversations

const url = 'https://api.asklucy.eu/v1/conversations?limit=25&agent_runs=exclude';
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?limit=25&agent_runs=exclude' \
  --header 'Authorization: Bearer <token>'

The caller’s own conversations, most recently active first. The runs of their owner agents are conversations too; they are left out unless agent_runs asks for them.

With q, one page of the best matches (no next_cursor), each with its match. The search is hybrid: by words (the title and the messages’ words) and by meaning (passages of the messages close to q, even without a word in common), the two rankings merged by reciprocal rank fusion. Only ever the caller’s own conversations, as without q. A message is found by meaning shortly after it’s written (it is embedded in the background); by words at once.

Authorizations

zitadel

Parameters

Query Parameters

cursor

string

The next_cursor of the previous page.

limit

integer

default: 25 >= 1 <= 100

string

<= 200 characters

Search the titles and the messages (the person’s and Lucy’s answers, not what tools returned), in any language.

By words: case and accents are ignored (ecole finds École); each word must be in the title or in one of the messages, and also finds the longer words it starts (fact finds factures), so it can search as you type; a title with a typo still matches.

By meaning (from 4 characters): “the invoice problem with the Belgian client” finds a conversation about a disputed bill from Antwerp. Only passages close enough count, so an unrelated query finds nothing. Blank is the same as no q.

agent_runs

string

default: exclude

Allowed values: exclude include only

exclude (the default) leaves agent runs out, include lists them too, only lists nothing else.

Responses

200

application/json

object

data

required

Array<object>

object

required

string

title

required

Set by the user, or by Lucy after the first answer.

string

created_at

required

string format: date-time

updated_at

required

Last message or change.

string format: date-time

created_by

required

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

answering_message_id

The answer Lucy is writing right now, if any.

string | null

expires_at

When the retention policy deletes it.

string | null format: date-time

local_device_id

The computer Lucy’s local tools reach in this conversation (one of the person’s devices), if any.

string | null

model

The model chosen for this conversation’s answers (a Model.id); null is Auto. It stays when the person can no longer choose, but then answers use Auto.

string | null

sandbox_retention

How long Lucy’s sandbox keeps what it saved: a paused workspace (the files of a conversation after a few idle minutes) and published pages. Days; a field that is null or absent is inherited. The organization’s value is the default and the ceiling: a person or a conversation can only choose a shorter time. The effective value is the shortest that applies, within the platform’s maximum.

object

snapshot_days

0 keeps no paused workspace (an idle sandbox is deleted with its files).

integer | null

artifact_days

integer | null

>= 1

agent_run

One of:

object
null

The agent run a conversation belongs to.

object

agent_id

required

string

run_id

required

string

identity

required

Whom the agent acts as.

owner: its creator, with exactly their access (their memory, their Microsoft 365, their quotas). Its runs are their conversations: they can read and continue them as themselves.
service: itself (its ID is its principal). It reaches only what it was given: its knowledge files and the tools below, never anyone’s Microsoft 365. Only org_admins create and see service agents; their runs are read-only.

string

Allowed values: owner service

read_only

required

True for service runs, which nobody can continue.

boolean

match

Only in search results (GET /conversations?q=…), where the search found it.

object

found_by

required

How the search found the conversation: words (in the title or the messages), meaning (a passage close to q), or both.

Array<string>

>= 1 items

Allowed values: words meaning

message_id

required

The message that matches best, to open the conversation at. Null when only the title matched.

string | null

role

required

One of:

string
null

string

Allowed values: user assistant

snippet

required

A few lines of that message, as plain text (no Markdown), with … where it was cut: around the words found, or, found only by meaning, the start of the passage that matched (no highlights then). Null when only the title matched.

string | null

highlights

required

The words found in snippet, in order, as [start, end) offsets in UTF-16 code units (JavaScript string indices). Empty when there is no snippet.

Array<object>

object

start

required

integer

end

required

integer

next_cursor

required

string | null

Example

{
  "data": [
    {
      "id": "conv_2YgP0x",
      "created_by": {
        "kind": "person"
      },
      "model": "mistral-large-4-0",
      "agent_run": {
        "identity": "owner"
      },
      "match": {
        "found_by": [
          "words"
        ],
        "message_id": "msg_9Qa1Zt",
        "role": "user",
        "snippet": "… the invoices for March are due on the 15th, and the …"
      }
    }
  ]
}

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.

403

The token is valid but lacks the role this needs.

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.