Jelliu API documentation

curl -X POST https://api.jelliu.co/api/widgets \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "agent_id": "efac2e32-c698-4018-974d-bbf4500916b5",
  "name": "Sitio web principal",
  "allowed_origins": [
    "https://www.clinicasonrisa.co"
  ]
}'

{
  "data": {
    "plaintext_api_key": "3462145765a6b6c238f79a1e13e10361c24d1740ec30d27bea22dd4106c04284",
    "id": "84b5aa0e-f6d6-4d88-b3ad-cd7a5a2aeb9e",
    "tenant_id": "58ffb2a3-7704-4790-bf60-a7235e42d0e4",
    "agent_id": "efac2e32-c698-4018-974d-bbf4500916b5",
    "name": "Sitio web principal",
    "allowed_origins": [
      "https://www.clinicasonrisa.co"
    ],
    "branding": {
      "primary_color": "#1C1D2B",
      "position": "bottom-right",
      "title": "Habla con nosotros"
    },
    "voice_enabled": false,
    "greeting_message": "¡Hola! ¿En qué te puedo ayudar?",
    "rate_limit_rpm": 30,
    "is_active": true,
    "created_at": "2026-09-15T13:05:44.902Z",
    "updated_at": "2026-09-15T13:05:44.902Z",
    "deleted_at": null
  }
}

Creates a web-chat widget bound to one of your agents and mints its widget API key. The widget is active immediately: embed it with the script from GET /widget-embed/{id}/embed.js, which identifies the widget by its id and does not need the key.

The plaintext key is returned once, as plaintext_api_key (64 hex characters). Only an HMAC-SHA256 digest is stored, so it cannot be retrieved again and there is no rotation endpoint. You only need it to call the public /widget/* endpoints from a server you control, in the x-widget-api-key header.

allowed_origins must list at least one full origin (for example https://www.example.com); runtime calls from any other page are refused. agent_id must be a live agent of your workspace: an id that matches no agent, a deleted agent, or an agent of another workspace is refused with 404 AGENT_NOT_FOUND (the three cases answer identically, so ids cannot be probed across workspaces).

Side effects. Inserts the widget row and writes an audit entry.

Idempotency. Not idempotent. Retrying after a timeout creates a second widget with a different id and key; list with GET /api/widgets first if unsure, and delete the duplicate.

Webhook events. audit.log_recorded when you subscribe to it. See Webhooks.

Access

Required scope: write.
Rate limit: General API — 120 requests/min per workspace (200 on Growth, 300 on Business, 600 on Enterprise). See Rate limits.
Plan: Available on every plan.

Authentication

AuthorizationBearer

Workspace API key: jl_ followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (Settings → API Keys) and sent as Authorization: Bearer jl_.... The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys.

Scope	GET / HEAD	POST / PUT / PATCH / DELETE	Admin-only routes
`read`	Yes	No	No
`write`	Yes	Yes	No
`full`	Yes	Yes	Yes

Operations restricted to admins or owners reject keys without the full scope with 403, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See Authentication.

Request

This endpoint expects an object.

agent_idstringRequiredformat: "uuid"

Agent that answers visitors. Must be a live agent of your workspace; otherwise 404 AGENT_NOT_FOUND.

namestringRequired1-200 characters

Internal name. Trimmed before validation.

allowed_originslist of stringsRequired

Full origins (URLs) the widget may be embedded on. At least one is required (At least one origin is required). Each entry must parse as a URL (Invalid url).

brandingobjectOptional

Widget look and copy. On write, primary_color is required whenever branding is sent, and the object REPLACES the stored branding (it is not merged). Widgets created without branding store {}, which is what POST /widget/init then returns.

Retired key (2026-09-15). logo_url is refused with 400 VALIDATION_FAILED — El campo branding.logo_url ya no existe: el widget no dibuja ningun logo. It is also stripped from every response, including the admin reads, POST /widget/init and the embed script, so a read-modify-write client never sends it back by accident. The widget draws no logo.

voice_enabledbooleanOptionalDefaults to false

Let visitors talk to the agent by voice.

greeting_messagestringOptional<=2000 characters

First message the chat shows. Trimmed; an empty string is treated as absent (stored as null).

rate_limit_rpmintegerOptional>=1Defaults to 30

Requests per minute allowed per widget credential on the public /widget/* endpoints (integer, 1 or more; defaults to 30). The workspace-wide cap of 300 requests/min across all of a workspace’s widgets applies on top and is not configurable.

Response

Widget created. The only response that ever contains plaintext_api_key.

dataobject

A web-chat widget configuration. Returned by every /api/widgets endpoint. Field names are snake_case. The widget API key is never part of this object; the plaintext is returned only once, as plaintext_api_key, when the widget is created.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error