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
- Open API & Integrations, then the API Tokens tab.
- Type a name that says what will use it, for example "Production integration" or "Zapier".
- Click Generate Token.
- 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.
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:
| Style | Auth | Best for |
|---|---|---|
Entry-point invoke (/entry-points/<entryState>/invoke) | API token | Server-to-server calls, multiple callable entries per workflow |
HTTPS listener (/api/open/listeners/<id>) | The bound API token | Form 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.
- Open API & Integrations, then Integrations.
- Select the workflow to expose.
- Turn on Iframe Embedding for it. This flips the workflow's
iframeEnabledswitch; only workflows with it enabled answer on the public embed endpoint. - 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.
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.
- Faberiq Embed plugin: use a native Faberiq Chat Gutenberg block or Elementor widget and paste a link from Studio. No OAuth credentials or API keys are needed in WordPress.
Install Faberiq Embed
- In Studio's Integrations screen, select your workflow and enable Public Chat & Embedding.
- Choose your chat appearance, then under Add to WordPress click Download WordPress plugin and Copy WordPress link.
- In WordPress, open Plugins → Add New Plugin → Upload Plugin, choose the downloaded ZIP, click Install Now, then Activate.
- Add a Faberiq Chat block to a page, or drag the Faberiq Chat widget into an Elementor page. Paste the link into Faberiq chat link.
- Adjust height, maximum width, alignment, and corner radius in the editor. Preview and publish the page.
The plugin requires WordPress 6.3 or later and PHP 7.4 or later. Elementor is optional; Elementor Pro is not required. Its WordPress.org directory listing is pending submission. Until it is published, use the ZIP installation above.
Your colors, chat title, and widget style travel with the copied link. Both /embed/chat/<workflowId> and /public/chat/<workflowId> links are accepted. Paste the URL itself, not iframe HTML. Only HTTPS Faberiq chat links are supported.
Under Settings → Faberiq Embed, optionally save a default chat link for blocks and widgets with no link of their own. A Shortcode block can use [faberiq_embed] for that default, or [faberiq_embed url="https://studio.faberiq.ai/embed/chat/YOUR_WORKFLOW_ID" height="600"] for a specific chat.
To defer loading the external chat until a visitor clicks, enable Load only after a visitor clicks on the block/widget or require it site-wide in plugin settings. Editor placeholders do not load the remote chat; use Open chat preview or WordPress's page preview to test it. When the chat loads, visitors connect to Faberiq, and their messages and session data are processed by the service. Public conversations use workspace credits, and disabling embedding in Studio shuts off access.
If your site uses a Content Security Policy, allow your Faberiq origin in frame-src. Clear your WordPress page cache after changing defaults. The older Faberiq Chat OAuth plugin is separate; existing [faberiq_chat] placements are not migrated automatically.
Related Pages
- Connectors overview: HTTPS listeners and External API connectors
- Workflows and Agents: entry states and triggers
- Billing and Credits: API and embed traffic consumes credits like any other execution