Skip to main content
Coding agents like Claude Code, Codex, and Claude Desktop can operate Fini’s public API directly. Install the Fini skills package and the agent knows the supported endpoints, their parameters, and their scopes, so it runs real operations against your workspace instead of guessing from stale training data. This guide covers both halves of that: giving the agent access to the API, and keeping its picture of the API current. For the raw endpoint surface, see the API overview.
The Fini skills package is a convenience layer over the same public REST API. It uses the same fini_... workspace API key and the same read and write scopes, and it doesn’t add a separate auth system or a separate set of capabilities. Anything the agent does through the skills, you can also do with a direct REST call. The skills just save you from writing the HTTP layer by hand.

​
What your agent needs

A coding agent is effective against Fini when it has two things, and they do different jobs.

Call the API

Install the Fini skills package so the agent runs operations directly (listing agents, exporting conversations, ingesting sources, publishing knowledge) rather than describing requests for you to wire up.

Read the current API

Point the agent at the live docs as Markdown, and add a rules file that tells it to check them. The API changes, and a model’s training data lags behind it.
The first capability lets the agent do things. The second keeps it from doing the wrong thing against an endpoint that has moved on since its training cut-off. Because the skills give operational access, the second matters more here than it would for a docs-only integration: a write-scoped agent can change live knowledge, so an agent working from a stale assumption can do real damage.

​
Install the Fini skills package

The skills package installs through skills.sh and works with any skills-aware agent. The install is one command, and it carries the same workspace API key and scopes as REST, so there’s nothing new to authenticate.
1

Install the skills package

Run the install command in your project root. 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 it when the agent prompts on first use, and keep it out of any file the agent commits to source control.
3

Run a Fini operation

Ask the agent for the task in plain language. It maps the request to the right endpoint, fills the parameters, and stays inside the scope on your key. Claude Code, Codex, Claude Desktop, and other skills-aware agents all work the same way.
Scope rules match REST exactly. A read-only key runs lists, fetches, and status checks. A write key is required to send conversation events, ingest or refresh sources, or change knowledge. Give the agent the narrowest scope its task needs.

​
Keep your agent current

Fini’s API evolves, and a coding agent’s training data lags behind it. Two things keep the agent accurate: a rules file that travels with your repo, and the live docs in a format the agent can pull on demand.

​
Add Fini to your rules file

Most agents load a rules file from the project root on every run. AGENTS.md is the cross-agent convention, and some agents read their own filename as well.
Add the section to CLAUDE.md (or AGENTS.md) in your project root. Claude Code loads it automatically on each run.
The section itself is the same wherever it lives:
Because the file loads into context on every run, the agent applies these rules without being reminded. Keep it short and specific. A rules file with ten vague principles gets skimmed and ignored; four concrete ones get followed.

​
Read the docs as Markdown

Every page on the docs site is available as Markdown. Append .md to any page URL, or use the Copy page button at the top of the page. For example, the API overview is at https://docs.usefini.com/en/api-reference/overview.md. This is the fastest way to drop an accurate, current page into an agent that can’t reach the docs any other way.

​
Use llms.txt for the whole site

For the entire docs site at once, a Markdown index is hosted at https://docs.usefini.com/llms.txt, with a single full-text export at https://docs.usefini.com/llms-full.txt. The index lists every page with a short description and is the better default for context. The full export is large and best reserved for an IDE assistant that ingests the whole site. For background on the format, see llmstxt.org.

​
What your agent can do

With the skills installed and a key in place, an agent can run most of the workspace through the API. The supported operations fall into the same families documented in the API reference:

Read agents

List bots and get the botId values other operations need.

Manage conversations

Export and fetch conversations, send message events, and delete in bulk.

Ingest sources

Discover, register, ingest, refresh, and delete source records.

Generate knowledge

Queue generation jobs and build the knowledge tree from sources.

Manage articles

Create, update, draft, publish, and delete live articles.

Organize knowledge

Manage folders, move articles, and scope folders to agents.

​
Common tasks

A few representative tasks, with the operations each touches and the scope it needs. Refresh a help center and regenerate knowledge. Requeue the source records with POST /v2/documents/public/refresh, queue generation for them with POST /v2/knowledge/public/bulk, then watch progress with POST /v2/knowledge/public/jobs/status. Needs write. The generated knowledge lands as drafts in Review and Approvals, so nothing reaches answers until you publish. Export and triage recent conversations. Pull conversations with GET /v2/hc-interactions/public, using the filters and cursor to page through a window. Needs only read. This is the basis for an agent that summarizes volume, finds gaps, or flags conversations for follow-up. Stand up a new bot’s knowledge from a sitemap. Crawl seed links with POST /v2/documents/public/deep-crawl/links, register and ingest the results with POST /v2/documents/public, generate knowledge in bulk, create folders with POST /v2/hc-folders/public, then assign them to the bot with POST /v2/hc-bot-folder-junctions/public. Needs write. Publish a batch of reviewed articles. Create or update articles with the manage-knowledge routes, publish drafts with POST /v2/hc-articles/:id/publish/public, and scope them to the right bot through the folder junctions. Needs write. Manage-knowledge routes write live, so these changes affect answers immediately, which is the intent here.

​
Best practices

To get the most out of the skills and avoid the common failure modes:
  • Keep the workspace API key server-side. The skills and REST share the same fini_... credential. A leaked key reads workspace data, and a write-scoped key changes knowledge until you revoke it in Deploy.
  • Give the agent the narrowest scope for the job. A read key is enough to export data or fetch conversations. Only issue a write key when the agent ingests sources or manages knowledge, and revoke it when the task is done.
  • Trust the route map over the HTTP verb. Scope is semantic, and some read operations use POST, so an agent that infers permissions from the method will be wrong. The API overview lists the scope for every route.
  • Default to the draft path for knowledge. Source-ingestion and generation routes send work through Review first, which is the safe default. Reserve the live-write manage-knowledge routes for cases where you mean to change answers immediately.
  • Have the agent read current docs before building against an endpoint. The API evolves and training data goes stale. The Markdown page or the llms.txt index is authoritative; the model’s memory of a field name is not.
  • Paginate conversation exports with the cursor. A single response is a page, not the whole set. An agent that stops at the first page will silently miss data.
  • Test a write-scoped agent against a non-production workspace first. Keys are workspace-scoped, so a separate workspace keeps a bad run from mutating live knowledge before you trust the flow.
  • Prefer the skills over hand-rolled HTTP. The package encodes the current operations and their scopes, so it stays correct across API changes that would break a hand-written client.

​
Why your agent isn’t working

The skills use the same workspace API key as REST. If a 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.
The key is valid but missing the operation’s scope. Check the route map in the API overview rather than the HTTP verb. Some read operations use POST.
Usually stale training data. The skills package encodes the current operations, so prefer it over hand-written requests, and have the agent read the live docs as Markdown when it needs endpoint detail.
It depends on the route. Source-ingestion and generation routes create drafts first, so they don’t 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 export is paginated. The agent likely read the first page and stopped. Have it follow the cursor until the result set is exhausted before treating the data as complete.
Keys are server-side credentials. The agent’s runtime or a proxy can strip the Authorization header, so confirm it’s actually being sent, and never ship the key to a browser even if you can get it to work.