Save an interface to share

POST

/interfaces

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

Saves a component so people of your organization can open it. conversation_id and message_id, when given, must be your own (400 otherwise); with only message_id, the conversation is the message’s.

Saving the same title from the same message_id again returns the interface saved before (same id, still 201), with code replaced when it changed.

Authorizations

zitadel

Parameters

Header Parameters

Idempotency-Key

string

<= 255 characters

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

Request Body^required

application/json

object

title

required

string

>= 1 characters <= 200 characters

code

required

At most 204800 bytes (200 KiB) of UTF-8.

string

>= 1 characters

conversation_id

One of your conversations.

string | null

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

message_id

A message of one of your conversations (of conversation_id, when given).

string | null

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

Example ^generated

{
  "title": "example",
  "code": "example",
  "conversation_id": "example",
  "message_id": "example"
}

Responses

201

Saved

application/json

object

required

string

title

required

The title of the answer’s jsx interface block.

string

<= 200 characters

code

required

The component’s source: one React function component, export default function App() { ... }, importing only react. The chat renders it; Lucy’s API never runs it.

string

created_at

required

string format: date-time

updated_at

required

Last save (saving the same block again with other code).

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

conversation_id

required

The conversation it came from. Null once that conversation is deleted, and for interfaces of other people (you can’t open their conversations).

string | null

message_id

required

The answer it came from; null like conversation_id.

string | null

mine

required

You saved it (you can delete it).

boolean

Example

{
  "id": "ifc_7QmT2b",
  "created_by": {
    "kind": "person"
  }
}

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.

Save an interface to share

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Example generated

Responses

201

Example

400

Example

Headers

401

Example

Headers

403

Example

Headers

429

Example

Headers

Request Body^required

Example ^generated