You opened Ask Lucy

POST

/me/opened

const url = 'https://api.asklucy.eu/v1/me/opened';
const options = {method: 'POST', 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 POST \
  --url https://api.asklucy.eu/v1/me/opened \
  --header 'Authorization: Bearer <token>'

The chat calls this when the person opens Ask Lucy (and when they come back to it). Their agents with an open trigger start, each at most once every 3 hours, so opening it again, or in several windows, runs them once. The answer lists the latest run of each of those triggers from the last 3 hours, newest first: the ones just started and the ones still worth showing, for “While you were away”. Without agents (or with none that has an open trigger) it lists none.

Authorizations

BearerToken

Responses

200

application/json

object

runs

required

The latest run of each of your open triggers from the last 3 hours, newest first.

Array<object>

object

agent_name

required

string

run

required

object

required

string

agent_id

required

string

version

required

The agent’s version this run used.

integer

trigger_id

required

The trigger that started it; null for manual runs.

string | null

trigger_type

string | null

Allowed values: webhook schedule open

triggered_by

required

Who started it, a user ID (manual) or the trg_ ID.

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

status

required

queued waits for the agent’s run in progress; skipped: a schedule fired while a run was still going, so this time didn’t run.

string

Allowed values: queued running succeeded failed cancelled skipped

input

required

The trigger’s fixed input, or a manual run’s input. Null for none.

payload

required

A webhook run’s request body (JSON, or a string). Data, never instructions. Null otherwise.

output

required

One of:

object
null

object

text

required

The answer’s text (its text parts, in order).

string | null

files

required

Files the run made (the answer’s output files).

Array<object>

object

required

string

name

required

string

content_type

required

string

size_bytes

required

integer

usage

required

object

steps

required

Tool calls.

integer

input_tokens

required

integer

output_tokens

required

integer

error

required

Why it failed or was skipped. Codes: those of Message.error (internal, timeout, interrupted, rate_limited, unavailable), and time_limit (max_minutes reached), quota_exceeded, agent_disabled (it was disabled or deleted while queued), not_allowed (its identity may no longer use agents), busy (skipped: a run was still going), conversation_deleted (its conversation was deleted while it ran).

object

code

required

string

message

required

string

conversation_id

required

The run’s conversation, once it is running. Owner runs are the owner’s conversations; service runs are read-only, for org_admins.

string | null

message_id

required

The answer that is the run (follow its events while running).

string | null

callback

The result’s delivery to the trigger’s callback_url, when it has one.

object

status

required

failed after 24 hours of retries.

string

Allowed values: pending delivered failed

attempts

required

integer

last_error

string | null

delivered_at

string | null format: date-time

created_at

required

string format: date-time

started_at

required

string | null format: date-time

finished_at

required

string | null format: date-time

Example

{
  "runs": [
    {
      "run": {
        "id": "run_2Wc8LmQz5RtYp1Xv7NsK",
        "trigger_type": "webhook",
        "identity": "owner",
        "status": "queued",
        "callback": {
          "status": "pending"
        }
      }
    }
  ]
}

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.

POST/me/opened

curl -X POST "https://api.asklucy.eu/v1/me/opened" \
  -H "Authorization: Bearer $LUCY_TOKEN"