The documents API is the public REST surface for knowledge ingestion. Use it to list document records, discover importable resources from connected providers, register those resources as Fini documents, and queue ingestion or refresh jobs.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.
Documents are inputs to Fini’s knowledge graph, not the knowledge itself. Once a document is ingested, its content flows through Review and Approvals like any other input — only approved content lands in Articles and powers agent answers. The API does not bypass the consolidation layer.
The five endpoints
List documents
GET /v2/documents/public — paginate through every document record in the workspace.Get document
GET /v2/documents/public/:id — fetch one document by ID.List provider resources
GET /v2/documents/public/resources/:provider — discover what’s importable from a connected provider.Register provider resources
POST /v2/documents/public/resources/:provider — create Fini document records for the resources you picked.Queue ingestion
POST /v2/documents/public — queue ingestion or refresh jobs.GET routes require the read scope. The two POST routes require write.
Two import flows
Document ingestion has two shapes depending on where the content lives.Web links
For arbitrary URLs, there’s no discovery step. Call Queue ingestion withsource: "web" and pass the URLs directly in documentIdsToAdd or documentIdsToRefresh. The values are URLs, not document IDs.
Connected providers
Fornotion, zendesk, and confluence, the flow is three calls:
Discover
Call List provider resources to see what’s importable. The response shape is provider-specific — Notion returns a flat list, Zendesk returns category trees, Confluence returns spaces with nested pages.
Register
Call Register provider resources with the resources you picked. This creates or updates Fini document records and returns the document IDs. This step alone does not queue ingestion.
Queue ingestion
Call Queue ingestion with
source set to the provider name and the document IDs you got back in step 2. This is the call that actually starts processing.Poll
Call List documents or Get document and watch
linkedJobStatus (PENDING, IN_PROGRESS, COMPLETED, FAILED), success, and error. Ingestion is asynchronous — the queue response only confirms that the job was accepted.Queue ingestion also accepts
source: "googledrive", but there’s no public resource-discovery route for Google Drive. Use that source only if you already have Drive document IDs from another flow.The async model
BothPOST routes return immediately with document IDs. They don’t return content, don’t return ingested paragraphs, and don’t confirm processing finished. The pattern is the same in both directions:
- Register provider resources returns
addedDocumentIdsandupdatedDocumentIds. Records exist; ingestion has not started. - Queue ingestion returns the same two arrays. Jobs are queued; processing is async.
| Field | What it tells you |
|---|---|
linkedJobStatus | Where the current ingestion job is. PENDING → IN_PROGRESS → COMPLETED or FAILED. |
success | Whether the last completed run produced usable content. |
error | Most recent error message, when a run failed. |
linkedKnowledgeId | Set once the document has been linked to an article or knowledge node. |
paragraphs | Populated after a successful run. |
Supported source values
| Source | Discovery route | Ingest values |
|---|---|---|
web | None — pass URLs directly | URLs |
googledrive | Not public | Document IDs from another flow |
notion | GET /resources/notion | Document IDs from Register |
zendesk | GET /resources/zendesk | Document IDs from Register |
confluence | GET /resources/confluence | Document IDs from Register |
files | Not in API — upload via dashboard | Document IDs (read only) |
Why ingestion isn’t working
POST /resources worked but nothing shows up in agent answers
POST /resources worked but nothing shows up in agent answers
Expected at two layers. First, resource registration only creates document records — you still need to call Queue ingestion to start processing. Second, even after processing finishes, document content lands in Review as a draft. It only affects answers once approved and published, and only for bots the article is attached to.
A queued job stays PENDING
A queued job stays PENDING
Ingestion is asynchronous. Poll List documents or Get document and watch
linkedJobStatus, success, and error. If the job is still PENDING after several minutes, check error on the document record.A web import fails immediately
A web import fails immediately
When
source is web, the values in documentIdsToAdd and documentIdsToRefresh must be URLs, not document IDs. The wire format reuses the same field names across sources, which is easy to miss.A provider-resources call returns 400
A provider-resources call returns 400
The provider isn’t valid for the public route, or it’s not connected in the workspace yet. The public provider routes accept
notion, zendesk, and confluence. Connect the provider in the dashboard first.Resources I expected aren't in the discovery response
Resources I expected aren't in the discovery response
Resources that have already been imported successfully from that provider are excluded from the response. This is intentional — discovery is for finding new content, not auditing what’s already in Fini. Use List documents with the provider as a
source filter to see what’s already imported.