The wire format still uses
document, documentId, and /v2/documents/... because that is the current API contract. In this reference, we call them sources because they are inputs to knowledge, not the knowledge your agents retrieve from directly.Reference pages
List sources
GET /v2/documents/public — paginate through every source record in the workspace.Get source
GET /v2/documents/public/:id — fetch one source record by ID.List provider resources
GET /v2/documents/public/resources/:provider — discover what is importable from a connected provider.Register provider resources
POST /v2/documents/public/resources/:provider — create source records for the resources you picked.Ingest sources
POST /v2/documents/public — queue ingestion or refresh jobs.Crawl links
POST /v2/documents/public/deep-crawl/links — discover more web URLs from one or more seed links.Refresh sources
POST /v2/documents/public/refresh — refresh existing source IDs.Delete sources
DELETE /v2/documents/public — delete source records, optionally deleting linked Articles too.Knowledge
Generate knowledge from sources, scaffold the first tree, and move from drafts into live knowledge.
Manage knowledge
Read, create, update, draft, publish, and delete live articles directly.
Organize knowledge
Manage folders, move articles between folders, and assign them to agents.
GET routes require read. Resource registration, ingestion, crawl, refresh, and delete routes require write.
Endpoint map
| 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 content from a connected provider. |
POST | /v2/documents/public/resources/:provider | write | Register provider resources as source records. |
POST | /v2/documents/public | write | Ingest new sources or refresh existing ones through the add-sources route. |
POST | /v2/documents/public/deep-crawl/links | write | Discover more web URLs from one or more seed links before ingesting them. |
POST | /v2/documents/public/refresh | write | Refresh existing source IDs. |
DELETE | /v2/documents/public | write | Delete source records, optionally deleting linked Articles too. |
Add sources
There are two ways to add sources into Fini through the public API:- Web links: pass URLs directly to Ingest sources.
- Connected providers: discover provider resources, register them, then ingest the returned source IDs.
zendesk, confluence, and notion.
| Source type | How to add it | What the discovery response looks like |
|---|---|---|
web | Call Ingest sources directly with URLs in documentIdsToAdd | No discovery call. You can optionally crawl first. |
zendesk | Call List provider resources, then Register provider resources, then Ingest sources | Category tree with nested sections and articles |
confluence | Call List provider resources, then Register provider resources, then Ingest sources | Array of spaces with nested pages |
notion | Call List provider resources, then Register provider resources, then Ingest sources | Flat array of importable resources |
NotionResource[], ZendeskCategory[], and ConfluenceSpace[].
Optional: crawl web links before ingesting
Crawling is useful when you have one or a few seed URLs and want Fini to discover more web pages before you ingest them. It is a separate API call, not behavior insidePOST /v2/documents/public.
Crawl the seed URLs
Call Crawl links. The response returns discovered URLs in
data.Pick the URLs you want to ingest
Use the returned URLs as the input set for your web-source ingestion flow.
Ingest them with the add-sources endpoint
Call Ingest sources with
source: "web" and place those URLs into documentIdsToAdd.The endpoint map above is the full public route surface for Sources. Use the child pages in this section for the detailed request and response references for each route family.
Refresh knowledge from changed sources
If you already have knowledge in Fini for a set of sources and the upstream content changes, the refresh path is: refresh the sources, filter the ones that actually changed, then bulk generate and save knowledge for just those source IDs.Refresh the existing source IDs
Call Refresh sources with the source IDs you already have. For web content, those are the source records created the first time you ingested the URLs.
Poll until the refresh completes
Use List sources or Get source and wait for
linkedJobStatus to move to COMPLETED.Filter to only the sources whose content changed
Call List sources with
changed=true. If you want only web content, also pass source=web. Keep the source records that already have a linkedKnowledgeId because those are the ones that already back knowledge in Fini.Bulk generate and save knowledge for those changed source IDs
Call Bulk generate knowledge with the changed
documentIds. Set isDraft: true if you want review before the update goes live. Set isDraft: false only when you want the update saved live immediately.Poll the knowledge jobs, then review if needed
Use Check knowledge jobs until the queued jobs finish. If you kept the updates as drafts, review and publish them before expecting agent answers to change.
When the generate-and-save job succeeds for a source-backed update, Fini syncs the linked article and clears that source’s
changed flag.Why the Sources API isn’t working
The source record exists but nothing shows up in agent answers
The source record exists but nothing shows up in agent answers
This is usually expected. Source registration and ingestion only get the raw content into Fini. You still need to create knowledge from that source, and the recommended path is to review the result before it goes live.
The ingestion job stays PENDING
The ingestion job stays PENDING
Ingestion is asynchronous. Poll List sources or Get source and watch
linkedJobStatus, success, and error. If a source stays PENDING for longer than expected, inspect error on the source record.A web source import fails immediately
A web source import fails immediately
When
source is web, the values in documentIdsToAdd and documentIdsToRefresh must be URLs, not source 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.Provider content I expected is missing from discovery
Provider content I expected is missing from discovery
Resources that have already been imported successfully from that provider are excluded from the response. Discovery is for finding new content, not auditing what is already in Fini. Use List sources with the provider as a
source filter to see what is already imported.A crawl or refresh request returns 400
A crawl or refresh request returns 400
Common causes are a malformed body, an empty required array, or trying to refresh a raw-file source. Web crawl expects seed URLs in
links, and refresh expects existing source IDs in documentIds.Delete or refresh fails with a server error
Delete or refresh fails with a server error
Retry once, then inspect the affected source IDs in List sources. If the problem persists, the workspace may contain one or more invalid or inaccessible records that need support help.