Recipe API and Webhooks

Requires the compatible Recipe external-trigger backend and desktop release. This documentation accompanies the implementation; production deployment is separate.

Configure a Recipe

  1. Add an External request trigger to your Recipe.
  2. Define up to ten request inputs. Each input has a name and a type: text, number, boolean, object, or array. All declared inputs are required. Names use letters, numbers, and underscores, starting with a letter or underscore.
  3. Connect those values to your conditions or actions, then save a version and install/update it.
  4. Enable the installation for the characters that may run it.
  5. For a webhook, open External access on the installed Recipe, choose a character, and create a webhook credential.

Credentials belong to your installation. They are never included in a published Recipe or shared graph. Creating or rotating a webhook shows its token once; copy it before closing the dialog. Rotation immediately invalidates the previous token. Disable the webhook to revoke access. The URL and bearer token are separate, so the token does not appear in URL logs.

The desktop app must remain open and connected. At most four Recipe commands may be preparing or executing on a desktop before it declines another external request. Existing run settings, cooldowns, and replacement/cancellation policies still apply. Actions already submitted cannot be recalled by cancellation.

GET /v1/recipes

Authenticate with your existing account API key:

curl 'https://api.getailicia.com/v1/recipes' \
  -H "Authorization: Bearer ${AI_LICIA_API_KEY}"

The response lists only your enabled, ready installations with an External request trigger. The id is an installed Recipe ID, not a draft or public catalogue ID. Each trigger advertises its required input names and types. This list does not guarantee that a desktop is currently available.

[
  {
    "id": "installed_recipe_id",
    "name": "Application alert",
    "description": "Speak when an external task finishes",
    "characterIds": ["character_id"],
    "triggers": [
      {
        "id": "external-alert",
        "name": "External request",
        "inputs": [
          {"key": "message", "label": "Message", "valueType": "TEXT", "required": true}
        ]
      }
    ]
  }
]

POST /v1/recipes/{recipeId}/runs

curl --request POST 'https://api.getailicia.com/v1/recipes/installed_recipe_id/runs' \
  -H "Authorization: Bearer ${AI_LICIA_API_KEY}" \
  -H 'Idempotency-Key: task-finished-123' \
  -H 'Content-Type: application/json' \
  --data '{"triggerId":"external-alert","characterId":"character_id","inputs":{"message":"Processing finished"}}'

triggerId identifies an External request trigger in that installed version. characterId may be omitted when exactly one character is assigned; otherwise select an assigned character explicitly. Inputs must contain exactly the declared fields, with matching JSON types, and fit within 16 KiB. Missing, extra, null, or incorrectly typed fields are rejected.

POST /v1/recipe-webhooks/{webhookId}

Use the URL and limited token generated by the app. This token can only invoke its configured installation, trigger, and character. It cannot list Recipes or manage the account.

curl --request POST "${RECIPE_WEBHOOK_URL}" \
  -H "Authorization: Bearer ${RECIPE_WEBHOOK_TOKEN}" \
  -H 'Idempotency-Key: task-finished-123' \
  -H 'Content-Type: application/json' \
  --data '{"inputs":{"message":"Processing finished"}}'

The initial webhook format accepts this documented JSON envelope. Third-party webhook payloads must be adapted to it; arbitrary vendor formats are not inferred automatically. Send credentials only from trusted applications or servers, not public browser code.

Acceptance, retries, and failures

Both POST routes wait briefly, up to the five-second acceptance window plus request/database overhead, for one compatible desktop to claim the request. A successful response is:

{"runId":"run_id","status":"RUNNING"}

202 Accepted confirms desktop acceptance. It does not promise successful execution of every node. A quickly finished run may already have a terminal status in this response. Follow execution and errors in the app; there is no public run-status endpoint in this version.

  • Include an Idempotency-Key of 1–128 visible ASCII characters on every POST.
  • Retry the same logical request with the same key and identical inputs, trigger, and character. The same installation/trigger scope is shared by the API and webhook.
  • Reusing a key with different inputs or character returns 409.
  • If the request expired without a desktop accepting it, retrying that key does not create a new run. Once the app is ready, deliberately send a new request with a new key.
  • Requests are not queued for replay when the app reconnects. A disconnect after acceptance can still prevent completion; acceptance is not an exactly-once guarantee for external side effects.
  • New requests use the existing per-account limiter, configured for 30 per minute per backend instance. Retries that resolve an existing request do not consume another admission. Existing generation/TTS limits still apply separately.
StatusMeaning
400Invalid trigger, inputs, character selection, or installation not enabled and ready
401Missing, invalid, disabled, or rotated bearer credential
404Installation not found or not owned by the caller
409Conflicting idempotency key or too many requests awaiting desktop acceptance
429Request rate exceeded; observe Retry-After
503No compatible desktop accepted the request before its deadline

Feature errors contain a bounded code and message, for example:

{"code":"DESKTOP_UNAVAILABLE","message":"No compatible desktop accepted this Recipe request. Open the desktop app and try a new request."}