REST API & webhooks

Overview

There are three ways in and one way out:

• A webhook trigger starts a workflow when your system sends an HTTP request to its URL. No API key is needed; the webhook has its own optional authentication.
• An API key (lc_live_) lets a script call the authenticated API as you, or connect an MCP client to the MCP server.
• A share link gives read or interactive access to one shared resource without a login.
• The HTTP Request node is the way out: your workflow calls an external API.

In the examples below, https://livecontext.ai is the cloud address. On a self-hosted Community Edition install, use the address of your own instance instead.

API keys

An API key looks like lc_live_ followed by 64 hexadecimal characters. You can hold up to 20 active keys, each with its own name, so you can give every script or client its own key and revoke one without touching the others.

Create a key

1. 1
   Open the key settings
   Go to Settings > MCP Server. The API keys section lists your keys.
2. 2
   Start a new key
   Select New key, then type a Name that says where the key is used (for example "Nightly export script").
3. 3
   Choose the access
   Leave Limit to specific tools off for a full-access key. Turn it on to pick tools under Tools; you must pick at least one.
4. 4
   Copy the key now
   Select New key to create it. The Key created dialog shows the full key once: copy it and store it somewhere safe, then select Done. Afterwards the list only shows a masked hint such as lc_live_...a1b2.

Revoke a key

In the API keys list, select the Revoke (bin) icon next to the key, then Revoke key to confirm. Revocation is immediate: the next request with that key fails with 401. Your other keys keep working.

Authenticate a request

Send the key in either header. Both forms are accepted everywhere a key is accepted:

X-API-Key: lc_live_xxxxxxxx
Authorization: Bearer lc_live_xxxxxxxx

curl https://livecontext.ai/api/auth/api-keys \
  -H "X-API-Key: lc_live_xxxxxxxx"

Keys are sent in a header, never in the URL. Treat a full-access key like a password: anyone who has it acts as you.

Manage keys over the API

A full-access key (or your signed-in session) can list and revoke keys directly. Creating one is different on LiveContext Cloud: it needs a sign-in from the last 5 minutes in the app, so an API key can never create another key (the request answers 403 reauthentication_required). Create keys in Settings, which asks you to sign in again when needed.

curl -X POST https://your-install.example/api/auth/api-keys \
  -H "X-API-Key: lc_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Reporting client", "scopes": ["table"]}'

The tool names you can use as scopes are the ones listed under Tools when you create a key in Settings. See MCP server for what each key can reach there.

Rate limits

Over the ceiling, the response is 429 Too Many Requests with an empty body and a Retry-After header giving the number of seconds until the window resets. Wait that long before you retry.

Errors from the API

Authentication errors come back as JSON with an error and a message field:

{
  "error": "Unauthorized",
  "message": "Invalid or unknown API key."
}

Call a webhook trigger

A Webhook trigger gives a workflow its own URL, shaped https://livecontext.ai/webhook/{token}, where the token starts with wh_. You find the URL on the trigger in the workflow builder, and every webhook you own is listed in Settings > Public Access, on the Webhooks tab. See Triggers to set one up and Public access & sharing for public URLs, forms, and token regeneration.

A webhook call needs no API key. Each webhook accepts exactly one HTTP method (GET, POST, PUT, PATCH, or DELETE; POST by default). Another method returns 405 Method Not Allowed.

curl -X POST https://livecontext.ai/webhook/wh_xxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"orderId": 42, "status": "paid"}'

Webhook authentication

A failed check returns 401 Unauthorized.

Reading the incoming request

The Webhook trigger exposes the request to the rest of the workflow:

What the caller gets back

By default the call is asynchronous: LiveContext acknowledges it and the workflow keeps running. The body is JSON with executionId, status, and message:

{
  "executionId": "3f6c2a8e-1b7d-4c55-9e0a-7d1f2b3c4d5e",
  "status": "triggered",
  "message": "Workflow run triggered successfully"
}

Reply from the workflow (Respond to Webhook node)

To have the workflow write the reply itself, add ?sync=true to the URL and place a Respond to Webhook node in the workflow.

curl -X POST "https://livecontext.ai/webhook/wh_xxxxxxxx?sync=true" \
  -H "Content-Type: application/json" \
  -d '{"question": "order status", "orderId": 42}'

The node outputs responded (false when no sync webhook call was waiting, for example on a manual run), statusCode, and contentType. Because responded=false is not a failure, the same workflow runs safely whether or not it was called in sync mode.

Public share links

Sharing an application or a conversation creates a share link. A share link gives access to that one resource, without a login: a shared application is interactive (visitors use it as you built it), and a shared conversation is read-only. A client presents the token as Authorization: ShareToken <token>. See Public access & sharing to create and revoke links, and Interfaces & apps and Marketplace for publishing.

Chat over the API

There are two chat surfaces, and they are not interchangeable.

Public chat endpoint (no login)

Built for chatbot apps wired to a chat trigger. It is synchronous request and response: no streaming, no stop endpoint.

Authenticated chat API (full-access key)

For driving a full conversation from your own backend. POST /api/v3/chat sends a message and returns {conversationId, streamId, model} right away while the agent works. Token and tool events stream over the WebSocket at /ws, not from this REST call. POST /api/v3/chat/stop with {"conversationId": "..."} stops an active answer. A key limited to specific tools cannot call this API (scope_forbidden).

Call external APIs from a workflow (HTTP Request node)

The HTTP Request node makes your workflow the caller. Methods: GET (default), POST, PUT, PATCH, DELETE. The URL, query values, header values, body, and auth values all accept {{...}} templates.

Content-Type is set from the body type when you do not supply it; Accept defaults to application/json, */*. An optional timeout (milliseconds) is capped at 300,000 ms (5 minutes).

Troubleshooting

For what each status code means, see Errors from the API and the webhook response statuses above. This table starts from what you observe.

Related pages