> ## 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.
# API overview
> The API surfaces available in Fini: public REST endpoints, the Fini skills package, and the contract for customer APIs Fini calls.
Fini exposes three API surfaces, depending on who initiates the request. Your backend can call Fini's public REST endpoints directly. An AI agent (Claude Code, Codex, Claude Desktop, or any skills-aware agent) can call supported public API operations through the Fini skills package. And Fini can call your own APIs when [Attributes](/en/api-reference/attributes) or [Actions](/en/api-reference/actions) run.
<Info>
Workspace API keys only authenticate requests you send to Fini. The `x-api-key` contract on [API contract](/en/api-reference/api-contract) is the opposite direction: the credential your systems expect when Fini calls them.
</Info>
## The API surfaces
<CardGroup cols={3}>
<Card title="REST API" icon="terminal">
Call Fini's public endpoints directly from your backend over HTTPS with a Bearer token.
</Card>
<Card title="Fini skills" icon="robot">
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.
</Card>
<Card title="Your APIs" icon="code" href="/en/api-reference/api-contract">
Expose customer-owned endpoints for Attributes and Actions. Fini calls them at runtime.
</Card>
</CardGroup>
The skills package is a convenience layer over supported REST operations, not a separate auth system. It uses the same workspace API key as the public API.
## Detailed pages available today
<CardGroup cols={3}>
<Card title="Agents" icon="robot" href="/en/api-reference/agents">
Workspace agents are the bots your team configures, tests, and exposes to customers.
</Card>
<Card title="Analytics" icon="chart-line" href="/en/api-reference/analytics">
Analytics summarize agent performance, knowledge usage, rule behavior, and escalation outcomes.
</Card>
<Card title="Prompts" icon="message" href="/en/api-reference/prompts">
Prompts define the agent's instructions, tone, policy boundaries, and versioned behavior.
</Card>
<Card title="Actions" icon="wand-magic-sparkles" href="/en/api-reference/actions">
Actions are typed tools the agent can run from Rulebook workflows to perform backend work.
</Card>
<Card title="Attributes" icon="id-card" href="/en/api-reference/attributes">
Attributes are customer context lookups that enrich the agent before it replies.
</Card>
<Card title="External API calls" icon="plug" href="/en/api-reference/actions-and-attributes">
External API calls are the outbound HTTP steps that power Actions and Attributes.
</Card>
<Card title="Tag groups" icon="tag" href="/en/api-reference/tag-groups">
Tag groups are classification buckets that organize tags for routing, reporting, and rules.
</Card>
<Card title="Tags" icon="tag" href="/en/api-reference/tags">
Tags are the individual labels Fini applies to conversations inside a tag group.
</Card>
<Card title="Intent rules" icon="route" href="/en/api-reference/intent-rules">
Intent rules are Rulebook workflows that run when a conversation matches a customer intent.
</Card>
<Card title="Guardrails" icon="shield-check" href="/en/api-reference/guardrails">
Configure reply checks and inspect policy runs and hit counts.
</Card>
<Card title="Business rules" icon="briefcase" href="/en/api-reference/business-rules">
Business rules are widget escalation workflows that enforce operational handoff policies.
</Card>
<Card title="Conversations" icon="comments" href="/en/api-reference/conversations">
Conversations are the customer interaction records and message events handled by Fini.
</Card>
<Card title="Refine with AI" icon="wand-magic-sparkles" href="/en/api-reference/refine-with-ai">
Refine with AI sessions capture AI-assisted recommendations for improving a Fini response.
</Card>
<Card title="Replays" icon="arrow-rotate-right" href="/en/api-reference/replays">
Replays run known conversations against the current agent configuration so you can compare behavior before and after changes.
</Card>
<Card title="Test sets" icon="vial" href="/en/api-reference/test-sets">
Test sets are regression suites built from conversations and evaluation criteria.
</Card>
<Card title="Sources" icon="book-open" href="/en/api-reference/sources">
Sources are imported files, URLs, and provider resources that feed Fini's knowledge graph.
</Card>
<Card title="Knowledge" icon="wand-magic-sparkles" href="/en/api-reference/knowledge">
Knowledge generation turns source content into proposed article and folder structures.
</Card>
<Card title="Manage knowledge" icon="book-open" href="/en/api-reference/manage-knowledge">
Articles are the reviewed knowledge records agents retrieve from at answer time.
</Card>
<Card title="Organize knowledge" icon="folder" href="/en/api-reference/organize-knowledge">
Folders organize articles into the tree structure assigned to one or more agents.
</Card>
</CardGroup>
## 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.
<Note>
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.
</Note>
### Agents
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `POST` | `/v2/bots/public` | `write` | Create a new agent in the workspace. |
| `GET` | `/v2/bots/public` | `read` | List the agents in the workspace and return the `botId` values other routes accept. |
| `DELETE` | `/v2/bots/:id/public` | `write` | Delete one agent. |
### Analytics
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/bots/:id/hc-analytics/public` | `read` | Fetch all analytics sections for one agent. |
| `GET` | `/v2/bots/:id/hc-analytics/:section/public` | `read` | Fetch one analytics section for one agent. |
### Prompts
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/bots/:id/hc-prompt/public` | `read` | Fetch the current merged prompts for one agent. |
| `GET` | `/v2/bots/:id/hc-prompt/history/public` | `read` | List saved prompt-version metadata for one agent, newest first. |
| `GET` | `/v2/bots/:id/hc-prompt/:promptId/public` | `read` | Fetch one saved prompt version as a merged prompt object. |
| `POST` | `/v2/bots/:id/hc-prompt/public` | `write` | Save a new prompt version for one agent. |
| `POST` | `/v2/bots/:id/hc-prompt/versions/public` | `write` | Create a draft prompt version for one agent. |
| `GET` | `/v2/bots/:id/hc-prompt/versions/:versionId/public` | `read` | Fetch one exact stored draft version for review. |
| `POST` | `/v2/bots/:id/hc-prompt/versions/:versionId/publish/public` | `write` | Publish one reviewed draft version. |
| `DELETE` | `/v2/bots/:id/hc-prompt/versions/:versionId/public` | `write` | Delete one unpublished draft version. |
### Actions
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/hc-tools/public` | `read` | List action records with `alwaysGet=false`. |
| `GET` | `/v2/hc-tools/:id/public` | `read` | Fetch one action by ID. |
| `POST` | `/v2/hc-tools/public` | `write` | Create an action record. |
| `PATCH` | `/v2/hc-tools/:id/public` | `write` | Update an action's name, schema, or configuration. |
| `DELETE` | `/v2/hc-tools/:id/public` | `write` | Delete one action. |
| `POST` | `/v2/hc-tools/:id/test-run/public` | `write` | Test-run an action's external API call chain. |
| `GET` | `/v2/hc-tools/:id/junctions/public` | `read` | List agent assignments for the action record. |
| `POST` | `/v2/hc-tools/junctions/public` | `write` | Update action agent assignments. |
### Attributes
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/hc-tools/public` | `read` | List attribute records with `alwaysGet=true`. |
| `GET` | `/v2/hc-tools/:id/public` | `read` | Fetch one attribute by ID. |
| `POST` | `/v2/hc-tools/public` | `write` | Create an attribute record. |
| `PATCH` | `/v2/hc-tools/:id/public` | `write` | Update an attribute's name, schema, or visibility flags. |
| `DELETE` | `/v2/hc-tools/:id/public` | `write` | Delete one attribute. |
| `POST` | `/v2/hc-tools/:id/test-run/public` | `write` | Test-run an attribute's external API call chain. |
| `GET` | `/v2/hc-tools/:id/junctions/public` | `read` | List agent assignments for the attribute record. |
| `POST` | `/v2/hc-tools/junctions/public` | `write` | Update attribute agent assignments. |
### External API calls
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/api-function-configs/public` | `read` | List external API call steps, optionally filtered by action or attribute. |
| `GET` | `/v2/api-function-configs/:id/public` | `read` | Fetch one external API call step. |
| `POST` | `/v2/api-function-configs/public` | `write` | Create one external API call step. |
| `PATCH` | `/v2/api-function-configs/:id/public` | `write` | Update one external API call step. |
| `DELETE` | `/v2/api-function-configs/:id/public` | `write` | Delete one external API call step. |
| `POST` | `/v2/api-function-configs/test-run/public` | `write` | Test one external API call without saving. |
### Intent Rules
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/hc-rules/public` | `read` | List Intent Rules. |
| `GET` | `/v2/hc-rules/fields-context/public` | `read` | Get fields-context options for Intent Rule setup. |
| `GET` | `/v2/hc-rules/:id/public` | `read` | Fetch one Intent Rule. |
| `POST` | `/v2/hc-rules/public` | `write` | Create an Intent Rule. |
| `POST` | `/v2/hc-rules/generate/public` | `write` | Use natural-language instructions and an LLM to generate intent-rule draft content. |
| `PATCH` | `/v2/hc-rules/:id/public` | `write` | Update an Intent Rule. |
| `GET` | `/v2/hc-rules/:id/versions/public` | `read` | List versions of an Intent Rule. |
| `GET` | `/v2/hc-rules/:id/versions/:versionId/public` | `read` | Fetch one Intent Rule version with its full tree. |
| `POST` | `/v2/hc-rules/:id/publish/public` | `write` | Publish a selected draft version and assign agents. |
| `POST` | `/v2/hc-rules/:id/versions/:versionId/restore-as-draft/public` | `write` | Copy a historical version into a new draft. |
| `DELETE` | `/v2/hc-rules/:id/versions/:versionId/public` | `write` | Delete one unpublished draft version. |
| `GET` | `/v2/hc-rules/:id/versions/:versionId/test-paths/public` | `read` | Generate test paths for one saved Intent Rule version. |
| `POST` | `/v2/hc-rules/:id/versions/:versionId/test-paths/run/public` | `read` | Run one test path against a saved Intent Rule version. |
| `POST` | `/v2/hc-rules/test-paths/config/public` | `read` | Generate test paths for an unsaved flow config. |
| `POST` | `/v2/hc-rules/test-paths/config/run/public` | `read` | Run one test path against an unsaved flow config. |
| `DELETE` | `/v2/hc-rules/:id/public` | `write` | Delete an Intent Rule. |
### Business Rules
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/business-rules/public` | `read` | List Business Rules, optionally filtered by `source=widget`. |
| `GET` | `/v2/business-rules/default/public` | `read` | List Fini-provided Business Rule templates. |
| `GET` | `/v2/business-rules/fields-context/public` | `read` | Get Business Rule fields. |
| `GET` | `/v2/business-rules/:id/public` | `read` | Fetch one Business Rule. |
| `POST` | `/v2/business-rules/public` | `write` | Create a custom or template-based Business Rule. |
| `POST` | `/v2/business-rules/:id/duplicate/public` | `write` | Duplicate one custom Business Rule. |
| `POST` | `/v2/business-rules/:id/evaluate/public` | `write` | Evaluate one Business Rule against supplied input context. |
| `GET` | `/v2/business-rules/:id/test-fields/public` | `read` | Return test fields for one saved Business Rule. |
| `POST` | `/v2/business-rules/test-fields/preview/public` | `read` | Preview test fields for an unsaved Business Rule tree. |
| `PATCH` | `/v2/business-rules/:id/public` | `write` | Update a Business Rule directly. |
| `DELETE` | `/v2/business-rules/:id/public` | `write` | Delete a Business Rule. |
### Tag groups
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/tag-groups/public` | `read` | List the tag groups available in the workspace, including Fini-shipped default groups. |
| `GET` | `/v2/tag-groups/:id/public` | `read` | Fetch one tag group by ID. |
| `POST` | `/v2/tag-groups/public` | `write` | Create a custom tag group. |
| `PUT` | `/v2/tag-groups/:id/public` | `write` | Update a custom tag group. |
| `DELETE` | `/v2/tag-groups/:id/public` | `write` | Delete a custom tag group. |
### Tags
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/tags/:id/public` | `read` | Fetch one tag by ID. |
| `GET` | `/v2/tag-groups/:id/tags/public` | `read` | List the tags inside one tag group. |
| `GET` | `/v2/tag-groups/tags/public` | `read` | List tags across one or more tag groups as a flat array. |
| `POST` | `/v2/tag-groups/:id/tags/public` | `write` | Create a tag inside a tag group. The path parameter is the tag group ID. |
| `PUT` | `/v2/tag-groups/tags/:id/public` | `write` | Update one tag. The path parameter is the tag ID. |
| `DELETE` | `/v2/tag-groups/tags/:id/public` | `write` | Delete one tag. The path parameter is the tag ID. |
### Conversations
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/hc-interactions/public` | `read` | Export conversations with filters and cursor pagination. |
| `GET` | `/v2/hc-interactions/:id/public` | `read` | Fetch one conversation by ID with the same public shape as the list endpoint. |
| `GET` | `/v2/hc-events/:id/metadata` | `read` | Fetch execution metadata for one Fini-authored event. |
| `POST` | `/v2/hc-interactions/events/public` | `write` | Send a message event into an existing conversation or start one by `botId`, then return the resulting public event array. |
| `POST` | `/v2/hc-interactions/:id/feedback/public` | `write` | Set or clear the feedback value on one event in a conversation. |
| `POST` | `/v2/hc-interactions/:id/feedback-resolved/public` | `write` | Mark a negatively rated event resolved or unresolved. |
| `POST` | `/v2/hc-interactions/:id/feedback-note/public` | `write` | Save or clear a teammate feedback note on one event. |
| `POST` | `/v2/hc-interactions/:id/evaluate-rule/:ruleId/public` | `write` | Evaluate one rule against an existing conversation. |
| `DELETE` | `/v2/hc-interactions/:id/public` | `write` | Delete one conversation by ID. |
| `DELETE` | `/v2/hc-interactions/public` | `write` | Delete up to 50 conversations in one request. |
### Refine with AI
See [Refine with AI](/en/api-reference/refine-with-ai) for the shared workflow and session object.
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `POST` | `/v2/fix-review/interactions/:id/events/:eventId/sessions/iterations/public` | `write` | Queue an AI-assisted fix-review iteration for one Fini response. |
| `GET` | `/v2/fix-review/interactions/:id/events/:eventId/session/public` | `read` | Get the active fix-review session for one Fini response. |
| `GET` | `/v2/fix-review/interactions/:id/events/:eventId/sessions/:sessionId/public` | `read` | Get one fix-review session by ID. |
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
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `POST` | `/v2/replays/public` | `write` | Create and run a replay from a target Fini response. |
| `GET` | `/v2/replays/interactions/:interactionId/public` | `read` | List replay conversations created from one original conversation. |
| `GET` | `/v2/replays/:id/public` | `read` | Fetch one replay conversation. |
| `GET` | `/v2/replays/:id/events/public` | `read` | Fetch the events for one replay conversation. |
See [Replays](/en/api-reference/replays) for replay modes, model overrides, and endpoint examples.
### Test sets
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/test-sets/public` | `read` | List test sets in the workspace. |
| `POST` | `/v2/test-sets/public` | `write` | Create a test set from existing conversation IDs. |
| `GET` | `/v2/test-sets/fields-context/public` | `read` | Get default criteria and deterministic-condition fields. |
| `GET` | `/v2/test-sets/:testSetId/public` | `read` | Fetch a test set with its criteria. |
| `PATCH` | `/v2/test-sets/:testSetId/public` | `write` | Update a test set. |
| `DELETE` | `/v2/test-sets/:testSetId/public` | `write` | Delete a test set. |
| `POST` | `/v2/test-sets/:testSetId/criteria/public` | `write` | Add criteria to a test set. |
| `PATCH` | `/v2/test-sets/:testSetId/criteria/:criteriaId/public` | `write` | Update one criterion. |
| `DELETE` | `/v2/test-sets/:testSetId/criteria/:criteriaId/public` | `write` | Delete one criterion. |
| `GET` | `/v2/test-sets/:testSetId/runs/public` | `read` | List runs for one test set. |
| `POST` | `/v2/test-sets/:testSetId/runs/public` | `write` | Start a new asynchronous run. |
| `GET` | `/v2/test-sets/runs/:runId/public` | `read` | Fetch one run and its detailed result. |
See [Test sets](/en/api-reference/test-sets) for object schemas and validation notes, then use the endpoint pages for request and response details.
### Reply rules
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/reply-behavior/public` | `read` | Get the workspace rules for no reply, internal comment, and direct reply behavior. |
| `GET` | `/v2/reply-behavior/fields-context/public` | `read` | Get fields, operators, sources, attributes, and tags available to reply rules. |
| `PUT` | `/v2/reply-behavior/:replyType/public` | `write` | Create or update one reply rule slot. |
See [Reply rules](/en/api-reference/reply-rules) for the behavior and condition shapes.
### Sources
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/documents/public` | `read` | List source records in the workspace. |
| `GET` | `/v2/documents/public/:id` | `read` | Fetch one source record by ID. |
| `GET` | `/v2/documents/public/resources/:provider` | `read` | Discover importable resources from a connected provider. |
| `POST` | `/v2/documents/public/resources/:provider` | `write` | Register provider resources as source records. |
| `POST` | `/v2/documents/public` | `write` | Ingest or refresh source records from URLs or source IDs. |
| `POST` | `/v2/documents/public/deep-crawl/links` | `write` | Crawl one or more seed links and return discovered URLs. |
| `POST` | `/v2/documents/public/refresh` | `write` | Requeue refresh for existing source IDs. |
| `DELETE` | `/v2/documents/public` | `write` | Delete source records, optionally deleting linked articles too. |
### Knowledge generation
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `POST` | `/v2/knowledge/public/tree/initialize` | `write` | Generate a tree-import template file from an initialization prompt. |
| `POST` | `/v2/knowledge/public/tree/persist` | `write` | Upload a tree file and persist it into the workspace knowledge graph. |
| `POST` | `/v2/knowledge/public` | `write` | Queue one knowledge-generation job from candidate knowledge text. |
| `POST` | `/v2/knowledge/public/bulk` | `write` | Queue generate-and-save jobs for multiple source IDs. |
| `POST` | `/v2/knowledge/public/jobs/status` | `read` | Check status for one or more background knowledge jobs. |
### Manage knowledge
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/hc-articles/public` | `read` | List articles. Use `type=live` or `type=draft` to filter. |
| `POST` | `/v2/hc-articles/ids/public` | `read` | Fetch one or more articles by ID. |
| `POST` | `/v2/hc-articles/public` | `write` | Create an article or draft article. |
| `PUT` | `/v2/hc-articles/:id/public` | `write` | Update an existing article. |
| `POST` | `/v2/hc-articles/:id/draft/public` | `write` | Create a draft from an existing article. |
| `POST` | `/v2/hc-articles/:id/publish/public` | `write` | Publish a draft article. |
| `GET` | `/v2/hc-articles/:id/history/public` | `read` | List saved history versions for one article. |
| `POST` | `/v2/hc-articles/:id/history/public` | `read` | Fetch one saved article version by version number. |
| `POST` | `/v2/hc-articles/:id/revert/public` | `write` | Revert an article to a saved history version. |
| `DELETE` | `/v2/hc-articles/:id/public` | `write` | Delete an article. |
### Organize knowledge
| Method | Path | Scope | Purpose |
| - | - | - | - |
| `GET` | `/v2/hc-folders/public` | `read` | Return the knowledge-folder snapshot, optionally filtered by `botId`. |
| `POST` | `/v2/hc-folders/public` | `write` | Create a knowledge folder. |
| `PUT` | `/v2/hc-folders/:id/public` | `write` | Update a folder's title, description, or active state. |
| `PUT` | `/v2/hc-folders/:id/move/public` | `write` | Move a folder under a different parent. |
| `PUT` | `/v2/hc-articles/:id/move/public` | `write` | Move an article into a different folder. |
| `DELETE` | `/v2/hc-folders/:id/public` | `write` | Delete a folder. |
| `POST` | `/v2/hc-bot-folder-junctions/public` | `write` | Assign or unassign folders to agents in bulk. |
## Authentication
Every public Fini endpoint authenticates with a **workspace API key** sent as a Bearer token.
<Steps>
<Step title="Create a key in Deploy → API Keys">
Go to [Deploy → API Keys](/en/deploy/api-keys). Create, reveal, and revoke credentials there. Keys are workspace-scoped, each workspace needs its own.
</Step>
<Step title="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.
</Step>
<Step title="Send it as a Bearer token">
Pass the key in the `Authorization` header:
~~~http theme={null}
Authorization: Bearer fini_xxxxxxxxxxxxxxxxx
~~~
</Step>
</Steps>
<Warning>
Keep API keys on the server side. Do not embed them in browser code, public mobile apps, or anywhere a user can read them. A leaked key can read workspace data, and write-scoped keys can ingest sources and modify knowledge until revoked.
</Warning>
## Workspace API key scopes
| Scope | What it allows | Current routes |
| - | - | - |
| `read` | Non-mutating list, fetch, and status operations | Agent listing, prompt reads, rule reads, tag and tag-group reads, conversation export and fetch-by-ID, source reads, knowledge tree snapshots, article reads, and knowledge-job status lookups |
| `write` | Mutation and execution operations | Prompt writes, rule mutations and draft generation, tag and tag-group mutations, conversation events and deletion, source discovery and ingestion, knowledge tree and article mutations, agent-folder assignments, and knowledge generation or import |
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
~~~http theme={null}
https://api-prod.usefini.com
~~~
All endpoint paths in the reference are appended to this base.
## 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.
<Steps>
<Step title="Install the skills package">
Run the install command in your project. 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 the key when the agent prompts for it on first use.
</Step>
<Step title="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`.
</Step>
</Steps>
<Info>
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](/en/knowledge/review). Manage-knowledge routes write articles directly to the knowledge graph, and organize-knowledge routes change that graph's structure and visibility immediately.
</Info>
## Why credentials live in Deploy
You create and revoke credentials from [Deploy → API Keys](/en/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
<AccordionGroup>
<Accordion title="401 Unauthorized" icon="lock">
The key is missing, malformed, or revoked. Confirm the header is exactly `Authorization: Bearer fini_...` with the full key and no extra whitespace. If the key was rotated, generate a new one in [Deploy → API Keys](/en/deploy/api-keys).
</Accordion>
<Accordion title="403 Forbidden" icon="shield-halved">
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`.
</Accordion>
<Accordion title="The skills package can't authenticate" icon="key">
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`.
</Accordion>
<Accordion title="Knowledge written via the API doesn't show up in agent answers" icon="book-open">
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.
</Accordion>
<Accordion title="The key works on your server but not from a browser" icon="server">
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.
</Accordion>
<Accordion title="A read endpoint returns an empty response" icon="circle-question">
Usually means the workspace has no matching data in the requested window or filter set. This is expected, not an error.
</Accordion>
</AccordionGroup>
## Related topics
- [Overview](/en/api-reference/actions-and-attributes.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
API Setup