Workspace API keys only authenticate requests you send to Fini. The
x-api-key contract on API contract is the opposite direction: the credential your systems expect when Fini calls them.The API surfaces
REST API
Call Fini’s public endpoints directly from your backend over HTTPS with a Bearer token.
Fini skills
Install the skills package and call supported public API operations from any AI agent (Claude Code, Codex, Claude Desktop) without writing the HTTP layer yourself.
Your APIs
Expose customer-owned endpoints for Attributes and Actions. Fini calls them at runtime.
Detailed pages available today
Agents
Workspace agents are the bots your team configures, tests, and exposes to customers.
Analytics
Analytics summarize agent performance, knowledge usage, rule behavior, and escalation outcomes.
Prompts
Prompts define the agent’s instructions, tone, policy boundaries, and versioned behavior.
Actions
Actions are typed tools the agent can run from Rulebook workflows to perform backend work.
Attributes
Attributes are customer context lookups that enrich the agent before it replies.
External API calls
External API calls are the outbound HTTP steps that power Actions and Attributes.
Tag groups
Tag groups are classification buckets that organize tags for routing, reporting, and rules.
Tags
Tags are the individual labels Fini applies to conversations inside a tag group.
Intent rules
Intent rules are Rulebook workflows that run when a conversation matches a customer intent.
Guardrails
Configure reply checks and inspect policy runs and hit counts.
Business rules
Business rules are widget escalation workflows that enforce operational handoff policies.
Macros
Manage workspace-wide saved replies for the native Inbox composer.
Conversations
Conversations are the customer interaction records and message events handled by Fini.
Refine with AI
Refine with AI sessions capture AI-assisted recommendations for improving a Fini response.
Replays
Replays run known conversations against the current agent configuration so you can compare behavior before and after changes.
Test Suite
Save cases, share criteria, organize collections and evaluate agent changes.
Sources
Sources are imported files, URLs, and provider resources that feed Fini’s knowledge graph.
Knowledge
Knowledge generation turns source content into proposed article and folder structures.
Manage knowledge
Articles are the reviewed knowledge records agents retrieve from at answer time.
Organize knowledge
Folders organize articles into the tree structure assigned to one or more agents.
Public route map
The tables below list the workspace-API-key routes covered by this reference. Use them as the quick route map, then jump into the detailed page for the endpoint family you need.Scope is semantic, not HTTP-method-based. Most
read endpoints are GET, but POST /v2/hc-articles/ids/public and POST /v2/knowledge/public/jobs/status are also read-scoped.Agents
Analytics
Prompts
Actions
Attributes
External API calls
Intent Rules
Business Rules
Tag groups
Tags
Conversations
Refine with AI
See Refine with AI for the shared workflow and session object.
Use the create response’s
sessionId and iterationId to poll a session route. The returned session includes latestIteration.status, the original and replayed answer snapshots, and changes with draft prompt, article, or rule IDs. Refine with AI does not publish those drafts automatically.
Replays
See Replays for replay modes, model overrides, and endpoint examples.
Test Suite
See Test Suite for shared models, criterion definitions and endpoint examples.
Reply rules
See Reply rules for the behavior and condition shapes.
Sources
Knowledge generation
Manage knowledge
Organize knowledge
Authentication
Every public Fini endpoint authenticates with a workspace API key sent as a Bearer token.1
Create a key in Deploy → API Keys
Go to Deploy → API Keys. Create, reveal, and revoke credentials there. Keys are workspace-scoped, each workspace needs its own.
2
Choose the right scope
The current dashboard create form starts with both Read and Write selected. Remove any scope your integration doesn’t need before you create the key.
3
Send it as a Bearer token
Pass the key in the
Authorization header:Workspace API key scopes
Most integrations only need one scope. If your workflow only reads data out of Fini, keep
Write unchecked. If it needs to send messages, refresh documents, or manage knowledge content, include Write.
Base URL
Using the Fini skills package
The Fini skills package teaches any compatible AI agent how to call the public API, so you don’t wire up the HTTP layer or hand-write request shapes yourself. It runs on the same workspace API key and the same scopes as REST. It’s a convenience layer over the supported operations, not a separate auth system.1
Install the skills package
Run the install command in your project. It adds the Fini skills to whichever agent environment you’re working in.
2
Provide your workspace API key
The skills authenticate with the same
fini_... key created in Deploy → API Keys. Paste the key when the agent prompts for it on first use.3
Ask the agent to run a Fini operation
Once installed, the agent knows the supported endpoints, their parameters, and their scopes. Claude Code, Codex, Claude Desktop, and other skills-aware agents can all call the public API directly. Scope rules are identical to REST: a
read-only key cannot run operations that require write.The public API has two write models. Source-ingestion routes and most knowledge-generation flows create inputs or drafts that still pass through Review and Approvals. Manage-knowledge routes write articles directly to the knowledge graph, and organize-knowledge routes change that graph’s structure and visibility immediately.
Why credentials live in Deploy
You create and revoke credentials from Deploy → API Keys because that workflow belongs in the product UI. The endpoint reference lives here so developer docs stay in one place.Why the API isn’t working
403 Forbidden
403 Forbidden
The key is valid but missing the endpoint’s required scope. Check the route map above rather than inferring from the HTTP method alone. Some
read endpoints use POST.The skills package can't authenticate
The skills package can't authenticate
The skills use the same workspace API key as REST. If a skill call fails with an auth error, re-provide the key. It’s the same
fini_... credential, not a separate token. Check the scope too: a read-only key can’t run operations that need write.Knowledge written via the API doesn't show up in agent answers
Knowledge written via the API doesn't show up in agent answers
It depends on the route. Source-ingestion routes and knowledge-generation routes usually create drafts first, so they do not affect answers until reviewed or published. Manage-knowledge routes can write live knowledge immediately, and organize-knowledge changes can change bot visibility right away.
The key works on your server but not from a browser
The key works on your server but not from a browser
Keys are server-side credentials. Proxies and client-side
fetch wrappers commonly strip the Authorization header, confirm it’s actually being sent from that environment, and don’t ship the key to a browser even if you can get it to work.A read endpoint returns an empty response
A read endpoint returns an empty response
Usually means the workspace has no matching data in the requested window or filter set. This is expected, not an error.

