Start a run from a webhook

POST

/hooks/{triggerId}/{token}

const url = 'https://api.asklucy.eu/v1/hooks/example/example';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '"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/hooks/example/example \
  --header 'Content-Type: application/json' \
  --data '"example"'

For other systems (GitHub, Zapier, Make, n8n, Power Automate, a script): POST to the trigger’s webhook_url as it is, like a Slack, Discord or Teams incoming webhook. The URL carries the token, so it needs no header and no Zitadel token. Treat it as a password: anyone who has it can start runs. Rotate it if it leaks (rotateAgentTriggerSecret). The token is never logged.

The body (at most 256 KB) is the run’s payload, read the way it was meant:

a body that is JSON is JSON, whatever its content type (curl -d says form-urlencoded);
a form (application/x-www-form-urlencoded, e.g. Slack) is an object of its fields, a list when a field repeats;
text/plain and any other UTF-8 text are a string.

Lucy treats the payload as data, never as instructions: the agent’s instructions decide what to do with it.

A retry with the same Idempotency-Key (or GitHub’s X-GitHub-Delivery) within 24 hours returns the first run instead of starting another.

Limits, on top of the organization’s: 60 accepted deliveries a minute per trigger, and 20 runs queued per agent.

Parameters

Path Parameters

triggerId

required

string

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

token

required

string

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

The trigger’s token (AgentTrigger.webhook_url has it). The URL is the credential.

Header Parameters

Idempotency-Key

string

<= 255 characters

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

X-GitHub-Delivery

string

<= 255 characters

Used as the idempotency key when Idempotency-Key is absent.

Request Body

Example ^generated

example

Responses

202

Accepted (or the run of an earlier delivery with the same key).

application/json

object

run_id

required

string

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

Example

{
  "status": "queued"
}

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.

404

No webhook at this URL, or it can’t run. That covers a wrong, missing or rotated-out token, an unknown trigger, a trigger or agent that is disabled or deleted, an owner who has left or may no longer use agents, and an organization with agents off. All of these answer the same.

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

413

The body is over 256 KB.

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

415

The body is neither JSON nor UTF-8 text.

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

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 a run from a webhook

Parameters

Path Parameters

Header Parameters

Request Body

Example generated

Example generated

Responses

202

Example

400

Example

Headers

404

Example

413

Example

415

Example

429

Example

Headers

Example ^generated

Example ^generated