Documents - Fini

The documents API is the public REST surface for knowledge ingestion. Use it to list document records, inspect one document in detail, discover importable resources from connected providers, register those resources as Fini documents, and queue ingestion or refresh jobs.

The three GET routes on this page require read. The two POST routes require write. The write routes are asynchronous.

Endpoint map

Method	Path	Scope	Purpose
`GET`	`/v2/documents/public`	`read`	List document records in the workspace.
`GET`	`/v2/documents/public/:id`	`read`	Fetch one document 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 and receive document IDs.
`POST`	`/v2/documents/public`	`write`	Queue ingestion or refresh jobs.

Two import flows

Web links

Call POST /v2/documents/public with source: "web". In that case, the values inside documentIdsToAdd and documentIdsToRefresh are URLs, not existing document IDs.

Connected providers

For notion, zendesk, and confluence, the flow is:

GET /v2/documents/public/resources/:provider
POST /v2/documents/public/resources/:provider
POST /v2/documents/public

The first POST only creates or updates document records. The second POST is the one that actually queues ingestion.

POST /v2/documents/public also accepts source: "googledrive", but there is no public resource-discovery route for Google Drive. Use that source only if you already have Google Drive document IDs from another flow.

List documents

GET /v2/documents/public
Authorization: Bearer fini_xxxxxxxxxxxxxxxxx

Results are ordered by updatedAt descending, then externalId descending.

Query parameters

Authorization

string

required

Bearer token containing your Fini workspace API key. Format: Bearer fini_...

limit

integer

default:"50"

Maximum number of documents to return.

cursor

string

Document ID to paginate from. Use the last document’s id for the next page or the first document’s id for the previous page.

direction

string

default:"next"

Pagination direction when a cursor is supplied. next moves toward older documents. previous moves back toward newer ones.

source

string

Optional document-source filter. Supported values are web, files, googledrive, zendesk, notion, and confluence.

english

boolean

Optional English-processing filter.

string

Exact document ID filter.

title

string

Case-insensitive partial match on the document title.

url

string

Case-insensitive partial match on the original source URL.

articleId

string

Filter by linked article or knowledge node ID.

linkedOperation

string

Filter by linked knowledge operation. Supported values are ADD_ARTICLE_TO_FOLDER, CREATE_SUBFOLDER_AND_ARTICLE, UPDATE_ARTICLE, and DO_NOTHING.

changed

boolean

Return only linked documents flagged as changed.

The response includes hasMore, but not a nextCursor. Use the returned document IDs themselves as cursors.

curl --request GET \
  --url 'https://api-prod.usefini.com/v2/documents/public?limit=25&source=notion' \
  --header 'Authorization: Bearer fini_your_api_key'

Response shape

documents

array

Array of document records.

Show document object

string

Document ID.

originalUrl

string

Original provider URL or web link.

title

string

Document title.

storageUrl

string | null

Internal storage URL when the document has been uploaded into Fini’s storage layer.

source

string

Source type such as web, notion, zendesk, or confluence.

externalId

string

Provider-specific external identifier, or the URL itself for web.

english

boolean

Whether English processing is enabled for the document.

baser

boolean

Whether BASER processing is enabled for the document.

success

boolean

Whether the latest processing run succeeded.

error

string

Latest processing error, if any.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-update timestamp.

mimeType

string

Document MIME type.

type

string | null

Provider-specific type, when available.

linkedKnowledgeId

string | null

Linked article or knowledge node ID, if this document has already been turned into knowledge.

linkedOperation

string | null

Operation used when the document last linked into knowledge.

linkedReason

string | null

Additional reason metadata for the linked operation, when present.

linkedJobId

string | null

Background job ID for the latest queued ingest or refresh.

linkedJobStatus

string | null

Background job status for the latest queued ingest or refresh. Values include PENDING, IN_PROGRESS, COMPLETED, and FAILED.

paragraphs

array

Extracted paragraph payload, if the document has already been processed. This can be large.

oldParagraphs

array

Previous paragraph snapshot used for change detection, when available.

hasMore

boolean

Whether more results exist beyond the current page.

{
  "documents": [
    {
      "id": "5d9f67a8-d853-4af4-b7ce-23ebba1245e5",
      "originalUrl": "https://www.notion.so/fini/Billing-FAQ-123456",
      "title": "Billing FAQ",
      "storageUrl": "gs://example/documents/5d9f67a8-d853-4af4-b7ce-23ebba1245e5",
      "source": "notion",
      "externalId": "123456",
      "english": true,
      "baser": false,
      "paragraphs": [
        "You can update your billing email from Settings."
      ],
      "oldParagraphs": [],
      "success": true,
      "error": "",
      "createdAt": "2026-05-22T06:05:34.221Z",
      "updatedAt": "2026-05-22T06:10:58.710Z",
      "mimeType": "text/markdown",
      "type": "page",
      "linkedJobId": "9f347ddb-1f90-43a2-ac9f-4f77f37a2c26",
      "linkedKnowledgeId": "8a4bb11a-0ef2-45df-9956-631e41e6cf16",
      "linkedOperation": "UPDATE_ARTICLE",
      "linkedReason": null,
      "linkedJobStatus": "COMPLETED"
    }
  ],
  "hasMore": false
}

Get one document

GET /v2/documents/public/:id
Authorization: Bearer fini_xxxxxxxxxxxxxxxxx

This route returns the same document shape as the list endpoint, but scoped to one document ID.

cURL

curl --request GET \
  --url 'https://api-prod.usefini.com/v2/documents/public/5d9f67a8-d853-4af4-b7ce-23ebba1245e5' \
  --header 'Authorization: Bearer fini_your_api_key'

List provider resources

GET /v2/documents/public/resources/:provider
Authorization: Bearer fini_xxxxxxxxxxxxxxxxx

This route lists resources that can be imported from a connected provider. The public route currently accepts notion, zendesk, and confluence.

The provider must already be connected in the workspace. A disconnected or unsupported provider returns 400 Bad Request.

The response shape is provider-specific:

Notion: a flat list of resources with externalId, title, originalUrl, mimeType, iconLink, and object.
Zendesk: category trees. Categories contain section children, and sections can contain article children.
Confluence: spaces with key, title, originalUrl, and nested pages.

Resources that have already been imported successfully from that provider are excluded from the returned list.

Register provider resources

POST /v2/documents/public/resources/:provider
Authorization: Bearer fini_xxxxxxxxxxxxxxxxx
Content-Type: application/json

Use this route after resource discovery. It creates or updates Fini document records for the resources you selected and returns the resulting document IDs.

This route does not queue ingestion by itself. Call POST /v2/documents/public next.

Request body

{
  "resources": [
    {
      "originalUrl": "https://www.notion.so/fini/Billing-FAQ-123456",
      "title": "Billing FAQ",
      "externalId": "123456",
      "mimeType": "text/markdown",
      "object": "page"
    }
  ]
}

Each resource object accepts:

originalUrl: provider URL
title: resource title
externalId: provider-specific identifier
mimeType: resource MIME type
storageUrl: optional storage URL
object: optional provider-specific type, for example a Notion object type

Response

200 OK

{
  "addedDocumentIds": [
    "5d9f67a8-d853-4af4-b7ce-23ebba1245e5"
  ],
  "updatedDocumentIds": []
}

Pass those IDs into documentIdsToAdd or documentIdsToRefresh on the next call to POST /v2/documents/public.

Queue document ingestion

POST /v2/documents/public
Authorization: Bearer fini_xxxxxxxxxxxxxxxxx
Content-Type: application/json

This route queues ingestion or refresh jobs.

Request body

{
  "source": "web",
  "documentIdsToAdd": [
    "https://docs.example.com/billing/refunds"
  ],
  "documentIdsToRefresh": [],
  "english": true,
  "baser": false
}

Field	Type	Description
`source`	`string`	Supported values are `web`, `googledrive`, `zendesk`, `notion`, and `confluence`. Defaults to `web`.
`documentIdsToAdd`	`string[]`	Items to ingest for the first time. For `source = "web"`, these values are URLs. For every other source, these values are document IDs.
`documentIdsToRefresh`	`string[]`	Items to refresh. For `source = "web"`, these values are URLs. For every other source, these values are document IDs.
`english`	`boolean`	Optional. Defaults to `true`.
`baser`	`boolean`	Optional. Defaults to `false`.

{
  "source": "web",
  "documentIdsToAdd": [
    "https://docs.example.com/billing/refunds",
    "https://docs.example.com/billing/invoices"
  ],
  "documentIdsToRefresh": [],
  "english": true,
  "baser": false
}

Response

200 OK

{
  "addedDocumentIds": [
    "5d9f67a8-d853-4af4-b7ce-23ebba1245e5"
  ],
  "updatedDocumentIds": []
}

The response only confirms which document records were queued. It does not mean processing has finished. Poll the read routes and inspect linkedJobStatus, success, and error.

Troubleshooting

403 Forbidden

The key is valid but does not include write. The two POST routes on this page require write.

The provider-resources route returns 400

The provider is invalid for the public route or not connected in the workspace. The public provider routes accept notion, zendesk, and confluence.

POST /resources worked but nothing changed in knowledge

Expected. Resource registration only creates or updates document records. You still need to call POST /v2/documents/public to queue ingestion.

A queued write stays pending

Writes are asynchronous. Poll the document read routes and watch linkedJobStatus, success, and error.

A web import fails immediately

When source is web, the values in documentIdsToAdd and documentIdsToRefresh must be URLs, not existing document IDs.

Documentation Index

​Endpoint map

​Two import flows

​Web links

​Connected providers

​List documents

​Query parameters

​Response shape

​Get one document

​List provider resources

​Register provider resources

​Request body

​Response

​Queue document ingestion

​Request body

​Response

​Troubleshooting

Endpoint map

Two import flows

Web links

Connected providers

List documents

Query parameters

Response shape

Get one document

List provider resources

Register provider resources

Request body

Response

Queue document ingestion

Request body

Response

Troubleshooting