Continue in a new conversation

POST

/conversations/{conversationId}/continue

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

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/continue \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

A long conversation re-reads all its earlier messages on every answer. This starts a new conversation of yours that carries on from a short summary of this one instead: Lucy writes the summary (what you are trying to do, what was decided, found or produced, the files used, what is still open) and reads it in every answer of the new conversation (carried_summary). The new conversation has no messages yet; its title is this one’s with (continued), and it keeps this one’s model while you may still choose it. The files of this conversation are not attached to the new one.

The summary is charged to you like an answer, and refused like one when a usage limit is reached (429 …/errors/quota-exceeded). Only your own conversations can be continued (404 otherwise), not while Lucy is answering (409 …/errors/answer-in-progress), and never an agent run (409 …/errors/not-continuable). 502 …/errors/summary-unavailable when the summary couldn’t be written: nothing is made or charged, try again; 503 with the same type when continuing is not configured.

Authorizations

BearerToken

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

Nothing to send (an empty object is accepted).

application/json

object

Example ^generated

{}

Responses

201

The new conversation, with carried_from and carried_summary.

application/json

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 this conversation’s folders are on (one of the person’s devices), if any.

string | null

local_folders

The folders of the person’s computer (local_device_id) added to this conversation in the desktop app, by name (never their paths). Lucy reaches them only for messages sent from the desktop app on that computer.

Array<object>

object

name

required

string

>= 1 characters <= 80 characters

added_at

required

string format: date-time

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

carried_from

One of:

object
null

object

required

string

title

required

string

carried_summary

The summary of the earlier conversation this one starts from: Lucy reads it in every answer here. Plain text with short headings. Only when one conversation is returned (GET /conversations/{id}, and the responses that create or change one); null in lists, and for a conversation that continues none.

string | null

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

Example

{
  "id": "conv_2YgP0x",
  "created_by": {
    "kind": "person"
  },
  "local_folders": [
    {
      "name": "Contracts"
    }
  ],
  "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 …"
  }
}

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.

409

The object isn’t in a state that allows this (e.g. Lucy is already answering).

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). A message or a continuation refused for a quota also emails the person, once per window (unless their email_limits is false), and, when it is the organization’s budget, its admins once a month.

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.

502

Another service Lucy needed didn’t answer as it should (the problem’s type says which).

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.

503

Storage for this isn’t configured on the server (e.g. …/errors/desktop-unavailable).

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.

POST/conversations/{conversationId}/continue

curl -X POST "https://api.asklucy.eu/v1/conversations/conv_7Hq2mKx9Rt/continue" \
  -H "Authorization: Bearer $LUCY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Continue in a new conversation

Authorizations

Parameters

Path Parameters

Header Parameters

Request Body

Example generated

Responses

201

Example

401

Example

Headers

404

Example

Headers

409

Example

Headers

429

Example

Headers

502

Example

Headers

503

Example

Headers

Example ^generated