> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usefini.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Coding agents

> Give your coding agent direct access to the Fini public API, plus the current docs and best practices it needs to build the right thing the first time.

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](/en/api-reference/overview).

<Info>
  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.
</Info>

## What your agent needs

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

<CardGroup cols={2}>
  <Card title="Call the API" icon="key">
    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.
  </Card>

  <Card title="Read the current API" icon="book-open">
    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.
  </Card>
</CardGroup>

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](https://agentskills.io) 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.

<Steps>
  <Step title="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.

    ```bash theme={null}
    npx skills add ask-fini/fini-skills
    ```
  </Step>

  <Step title="Provide your workspace API key">
    The skills authenticate with the same `fini_...` key created in [Deploy → API Keys](/en/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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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.
</Note>

## 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.

<Tabs>
  <Tab title="Claude Code">
    Add the section to `CLAUDE.md` (or `AGENTS.md`) in your project root. Claude Code loads it automatically on each run.
  </Tab>

  <Tab title="Codex">
    Add the section to `AGENTS.md` in your project root. Codex reads it as part of its working context.
  </Tab>

  <Tab title="Cursor">
    Add the section to `AGENTS.md`, or as a rule file under `.cursor/rules`. Cursor applies project rules automatically.
  </Tab>

  <Tab title="Other agents">
    Most agents load a project rules file on startup. Check your agent's docs for the exact filename, then add the same Fini section.
  </Tab>
</Tabs>

The section itself is the same wherever it lives:

```markdown theme={null}
## Fini

Use the Fini public API to manage knowledge, conversations, and sources
programmatically. The ask-fini/fini-skills package is installed: call supported
operations through it rather than hand-writing HTTP requests.

Base URL: https://api-prod.usefini.com
Auth: Authorization: Bearer fini_... (workspace API key, server-side only)

Rules:
- Scopes are semantic, not HTTP-method-based. A read key cannot run write
  operations, and some read operations use POST. Check the route map in the API
  reference, not the HTTP verb.
- Knowledge writes have two paths. Source-ingestion and generation routes create
  drafts that pass through Review and do not affect answers until published.
  Manage-knowledge routes write live articles immediately. Default to the draft
  path unless the task explicitly calls for a live write.
- Before relying on an endpoint's shape, read the current page as Markdown
  (append .md to any docs URL). Do not assume request or response fields from
  training data.
- Export conversations with cursor pagination. Do not assume a single page is
  the full result set.
```

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](https://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:

<CardGroup cols={3}>
  <Card title="Read agents" icon="robot" href="/en/api-reference/list-agents">
    List bots and get the `botId` values other operations need.
  </Card>

  <Card title="Manage conversations" icon="comments" href="/en/api-reference/list-conversations">
    Export and fetch conversations, send message events, and delete in bulk.
  </Card>

  <Card title="Ingest sources" icon="database" href="/en/api-reference/sources">
    Discover, register, ingest, refresh, and delete source records.
  </Card>

  <Card title="Generate knowledge" icon="wand-magic-sparkles" href="/en/api-reference/knowledge">
    Queue generation jobs and build the knowledge tree from sources.
  </Card>

  <Card title="Manage articles" icon="book-open" href="/en/api-reference/manage-knowledge">
    Create, update, draft, publish, and delete live articles.
  </Card>

  <Card title="Organize knowledge" icon="folder" href="/en/api-reference/organize-knowledge">
    Manage folders, move articles, and scope folders to agents.
  </Card>
</CardGroup>

### 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](/en/knowledge/review), 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

<AccordionGroup>
  <Accordion title="The skills package can't authenticate" icon="key">
    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`.
  </Accordion>

  <Accordion title="403 Forbidden on a supported operation" icon="shield-halved">
    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`.
  </Accordion>

  <Accordion title="The agent calls endpoints that don't exist or sends the wrong shape" icon="robot">
    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.
  </Accordion>

  <Accordion title="Knowledge the agent wrote doesn't show up in answers" icon="book-open">
    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.
  </Accordion>

  <Accordion title="A conversation export looks incomplete" icon="list">
    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.
  </Accordion>

  <Accordion title="The key works locally but not from the agent's runtime" icon="server">
    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.
  </Accordion>
</AccordionGroup>


## Related topics

- [List agents](/en/api-reference/list-agents.md)
- [Create agent](/en/api-reference/create-agent.md)
- [Delete agent](/en/api-reference/delete-agent.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.