Skip to main content
POST
/
v2
/
documents
/
public
curl --request POST \
  --url 'https://api-prod.usefini.com/v2/documents/public' \
  --header 'Authorization: Bearer fini_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "source": "web",
    "documentIdsToAdd": [
      "https://docs.example.com/billing/refunds",
      "https://docs.example.com/billing/invoices"
    ],
    "documentIdsToRefresh": [],
    "english": true,
    "baser": false
  }'

{
  "addedDocumentIds": [
    "5d9f67a8-d853-4af4-b7ce-23ebba1245e5"
  ],
  "updatedDocumentIds": []
}
Queues ingestion or refresh jobs for sources. This is the call that actually starts processing, both for web links, which skip registration entirely, and for provider content, where you have already called Register provider resources.
This route is asynchronous. The response only confirms the job was queued. Poll List sources or Get source and watch linkedJobStatus, success, and error to track progress.
The request body still uses documentIdsToAdd and documentIdsToRefresh because that is the current API contract. On this page, those values are described as source inputs or source IDs.

​
Add sources with this endpoint

POST /v2/documents/public is the add-sources endpoint for both web content and connected providers:
Input typeWhat goes in documentIdsToAddNotes
webURLsYou can optionally crawl first with POST /v2/documents/public/deep-crawl/links.
zendeskSource IDs returned after registerDiscovery response is a nested category tree.
confluenceSource IDs returned after registerDiscovery response is an array of spaces with nested pages.
notionSource IDs returned after registerDiscovery response is a flat array of resources.
Crawling is not part of POST /v2/documents/public itself. If you want Fini to expand a seed URL into more pages first, call POST /v2/documents/public/deep-crawl/links, then send the returned URLs into documentIdsToAdd on this route.

​
Headers

​
Authorization
string
required
Bearer token containing your Fini workspace API key. Format: Bearer fini_... The key needs write scope.
​
Content-Type
string
required
application/json

​
Body parameters

​
source
string
default:"web"
Source type. Supported values: web, googledrive, notion, zendesk, confluence. Determines what the documentIdsToAdd and documentIdsToRefresh arrays contain.
​
documentIdsToAdd
array
Items to ingest for the first time. For source: "web", these values are URLs. For every other source, these values are source IDs returned by Register provider resources or already in your workspace.
​
documentIdsToRefresh
array
Items to refresh. Same value semantics as documentIdsToAdd: URLs for web, source IDs for everything else.
​
english
boolean
default:"true"
Whether to apply English-specific processing.
​
baser
boolean
default:"false"
Whether to apply BASER processing.
The same field names carry different value types depending on source. This is the most common cause of failed web imports.
curl --request POST \
  --url 'https://api-prod.usefini.com/v2/documents/public' \
  --header 'Authorization: Bearer fini_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "source": "web",
    "documentIdsToAdd": [
      "https://docs.example.com/billing/refunds",
      "https://docs.example.com/billing/invoices"
    ],
    "documentIdsToRefresh": [],
    "english": true,
    "baser": false
  }'

​
Response

​
addedDocumentIds
array
Source IDs for items that were queued for first-time ingestion.
​
updatedDocumentIds
array
Source IDs for items that were queued for refresh.
{
  "addedDocumentIds": [
    "5d9f67a8-d853-4af4-b7ce-23ebba1245e5"
  ],
  "updatedDocumentIds": []
}

​
Polling for completion

The response above means jobs are queued, not finished. Poll the read routes:
Poll
curl --request GET \
  --url 'https://api-prod.usefini.com/v2/documents/public/5d9f67a8-d853-4af4-b7ce-23ebba1245e5' \
  --header 'Authorization: Bearer fini_your_api_key'
Watch these fields on the document record:
FieldMeaning
linkedJobStatusPENDING → IN_PROGRESS → COMPLETED or FAILED
successtrue when the latest run produced usable content
errorNon-empty string when the latest run failed
paragraphsPopulated after a successful run
linkedKnowledgeIdSet once the document has been linked to an article
A COMPLETED job means the source was processed. It does not mean its content is live in agent answers. Source ingestion still needs to flow through Knowledge, and review is the recommended step before publishing.

​
Errors

Common causes: unsupported source value, missing required fields, or passing source IDs in documentIdsToAdd when source: "web" because web imports expect URLs.
The API key is missing, malformed, revoked, or invalid. Confirm Authorization: Bearer fini_... with the full key.
The API key doesn’t include the write scope, or it’s scoped to a different workspace.
The job was queued successfully but failed during fetch. Check error on the document record. Common causes: URL behind authentication, robots.txt blocks, or content type Fini doesn’t extract.
The provider connection may have expired or lost permissions on the resource. Reconnect the provider in the dashboard and refresh the source.
Ingestion is queued. Under heavy workspace load, PENDING can persist longer than usual. If a job sits for more than 15 minutes, contact support with the linkedJobId from the source record.