Skip to main content

API and Integrations

Everything in this page lives under API & Integrations in the left navigation (the /api-docs page). It has three tabs:

  • Documentation: quick-start guides and an interactive API explorer.
  • API Tokens: create and manage personal access tokens.
  • Integrations: turn a workflow into an embeddable chat widget for your website.

Personal API Tokens​

A personal API token lets a program act as you: same workspace, same projects, no browser login. Tokens start with the prefix af_pat_.

Creating a token​

  1. Open API & Integrations, then the API Tokens tab.
  2. Type a name that says what will use it, for example "Production integration" or "Zapier".
  3. Click Generate Token.
  4. The full token value is displayed once. Copy it immediately and store it in your secret manager; after you close the panel, Faberiq only ever shows the first few characters again.

The token list shows each token's name, prefix, creation date, and when it was last used, which makes stale tokens easy to spot.

Using a token​

Send it on every request in either header:

Authorization: Bearer af_pat_xxxxxxxxxxxxxxxx

or

x-api-token: af_pat_xxxxxxxxxxxxxxxx

Rotating and revoking​

  • Rotate issues a new secret for the same token entry and shows it once. The old secret stops working immediately, so update every integration that used it.
  • Revoke deletes the token permanently.
danger

A leaked token grants your workspace access until you rotate or revoke it. Treat tokens like passwords: never commit them to code, and prefer one token per integration so you can revoke narrowly.

The Public API​

The programmatic surface lives under /api/open and authenticates with your API token. The best reference is the live one: the Documentation tab embeds an interactive API explorer, and the raw OpenAPI document is served at /api/openapi.json (use it to generate clients).

Discover your workspace​

export AF_BASE_URL="https://studio.faberiq.ai"
export AF_TOKEN="af_pat_..."

curl -H "Authorization: Bearer $AF_TOKEN" "$AF_BASE_URL/api/open/me"
curl -H "Authorization: Bearer $AF_TOKEN" "$AF_BASE_URL/api/open/projects"
curl -H "Authorization: Bearer $AF_TOKEN" "$AF_BASE_URL/api/open/projects/<projectId>/workflows"

Invoke a workflow​

Workflows expose callable entry points (the same entry states that channels use). Discover them, then invoke one:

# List entry points
curl -H "Authorization: Bearer $AF_TOKEN" \
  "$AF_BASE_URL/api/open/projects/<projectId>/workflows/<workflowId>/entry-points"

# Invoke one
curl -X POST \
  "$AF_BASE_URL/api/open/projects/<projectId>/workflows/<workflowId>/entry-points/<entryState>/invoke" \
  -H "Authorization: Bearer $AF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "message": "Hello" }, "stream": false }'

Set "stream": true to receive a text/event-stream response instead of a single JSON payload.

Converse with a workflow​

For chat-style integrations there is a conversation endpoint that accepts a message history and keeps the exchange attached to a conversation:

POST /api/open/projects/<projectId>/workflows/<workflowId>/conversation

You can pass an entryState to choose the entry point (invalid names are rejected with a hint to use the entry-points listing). Related endpoints list your conversations (GET /api/open/projects/<projectId>/conversations) and let you message an agent directly (POST /api/open/projects/<projectId>/agents/<agentId>/messages).

HTTPS listeners​

An HTTPS Listener is a connector (added from the Connectors tab) that gives one workflow entry a stable public URL, locked to one of your API tokens. You choose the HTTP method and whether responses stream.

curl -sS -X POST "$AF_BASE_URL/api/open/listeners/<listenerId>" \
  -H "Authorization: Bearer $AF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Hi, schedule a meeting tomorrow at 10 AM EST." }
    ],
    "stream": false
  }'

For streaming, add ?stream=true, send "stream": true, and read the response as server-sent events.

If you receive 403 API token is not authorized, the listener is bound to a different token than the one you sent: re-bind the connector or use the matching token.

Which trigger style to use​

A workflow can be reached three ways from the outside, all built on entry states:

StyleAuthBest for
Entry-point invoke (/entry-points/<entryState>/invoke)API tokenServer-to-server calls, multiple callable entries per workflow
HTTPS listener (/api/open/listeners/<id>)The bound API tokenForm handlers, CRMs, automation platforms that just need one URL
Embed chat (below)None (public)Website visitors chatting with the workflow

The Embeddable Chat Widget​

The Integrations tab turns any workflow into a chat widget you can paste into a website.

  1. Open API & Integrations, then Integrations.
  2. Select the workflow to expose.
  3. Turn on Iframe Embedding for it. This flips the workflow's iframeEnabled switch; only workflows with it enabled answer on the public embed endpoint.
  4. Copy the generated embed code. It is a plain <iframe> pointing at /embed/chat/<workflowId>, with the width, height, and alignment you pick in the tab. A live preview shows exactly what visitors get.

The embed URL accepts optional query parameters for styling: primaryColor, bgColor, title, hideHeader=true, and style (classic, compact, or bubbles). The widget also shows the workflow's starter prompts and your organization name.

Public by design

An embedded workflow is public: anyone who has the embed code (or finds the URL) can chat with it, without logging in, and each conversation consumes your workspace credits like any other execution. Only enable iframe embedding on workflows you intend to be public, and disable the toggle to shut access off instantly.

Under the hood the widget uses two open endpoints with permissive CORS: GET /api/open/embed/<workflowId>/config (starter prompts and org name) and POST /api/open/embed/<workflowId>/chat with { "messages": [{ "role": "user", "content": "..." }] }. You can call them from your own custom front end if the iframe does not fit your site.

WordPress​

Two options, simplest first:

  • Paste the iframe: in the WordPress block editor, add a Custom HTML block and paste the embed code from the Integrations tab. Done.
  • The Faberiq Chat plugin: a floating chat panel that mirrors the Faberiq chat UI, with login and history. Install the faberiq-chat plugin folder under /wp-content/plugins/, activate it, then open Settings, then Faberiq Chat to configure the OAuth credentials and pick your project and agent. Place the widget with the [faberiq_chat] shortcode on specific pages, or enable auto-embed to show it site-wide. The plugin needs its OAuth redirect URI (https://your-site.com/wp-admin/admin-post.php?action=faberiq_oauth_callback) registered with your Faberiq auth provider, so it is aimed at teams with an admin comfortable doing that; most sites are happier with the iframe.