Overview

Public API for Lucy (enterprise customers).

Lucy API 0.1.0

The API behind lucy-ui, also open to customers’ own systems.

Authentication

Every request carries a Zitadel access token (Authorization: Bearer …). People sign in through their company’s identity provider in Zitadel (authorization code + PKCE). Customer systems use a Zitadel service user of their organization (client credentials or JWT profile). Lucy has no sign-up, password or API-key endpoints of its own.

The token decides the tenant and the permissions:

organization: urn:zitadel:iam:user:resourceowner:id
roles: urn:zitadel:iam:org:project:roles (member, org_admin, auditor); operations list theirs under x-required-roles.

Every object belongs to exactly one organization. An ID from another organization behaves as if it didn’t exist (404).

Conventions

IDs are opaque strings with a type prefix: conv_, msg_, file_, ifc_, alr_, aud_, exp_, dev_, con_, for agents agt_, trg_, run_, and for memory proc_, prv_, ent_, rel_, fact_. User IDs are Zitadel’s.
Timestamps are RFC 3339 in UTC.
Lists use cursor pagination: pass cursor from the previous page’s next_cursor; next_cursor is null on the last page.
Errors are application/problem+json (RFC 9457).
POSTs that create something accept an Idempotency-Key header: a retry with the same key returns the first result instead of creating a second one (keys are kept 24 hours).
Rate limits are per organization. Responses carry RateLimit and RateLimit-Policy headers; over the limit you get 429 with Retry-After.
Every response has an X-Request-Id; quote it to support.

Information

License: Proprietary (In Good Company SARL)
OpenAPI version: 3.1.0

Operations

Authentication

zitadel

Zitadel access token for the Lucy project (user or service user).

Security scheme type: openIdConnect

OpenID Connect URL: https://id.asklucy.eu/.well-known/openid-configuration