Ingest sources

> ## 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.

# Ingest sources

> Queue first-time ingestion or refresh jobs for web links or existing source IDs. The call returns immediately because processing is async.

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](/en/api-reference/register-provider-resources).

<Warning>
  This route is asynchronous. The response only confirms the job was queued. Poll [List sources](/en/api-reference/list-sources) or [Get source](/en/api-reference/get-source) and watch `linkedJobStatus`, `success`, and `error` to track progress.
</Warning>

<Note>
  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.
</Note>

## Add sources with this endpoint

`POST /v2/documents/public` is the add-sources endpoint for both web content and connected providers:

* For `web`, place URLs directly in `documentIdsToAdd`.
* For `zendesk`, `confluence`, and `notion`, first use [List provider resources](/en/api-reference/list-provider-resources) and [Register provider resources](/en/api-reference/register-provider-resources), then place the returned source IDs in `documentIdsToAdd`.

| Input type | What goes in `documentIdsToAdd` | Notes |
| - | - | - |
| `web` | URLs | You can optionally crawl first with `POST /v2/documents/public/deep-crawl/links`. |
| `zendesk` | Source IDs returned after register | Discovery response is a nested category tree. |
| `confluence` | Source IDs returned after register | Discovery response is an array of spaces with nested pages. |
| `notion` | Source IDs returned after register | Discovery response is a flat array of resources. |

<Info>
  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.
</Info>

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token containing your Fini workspace API key. Format: `Bearer fini_...` The key needs `write` scope.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

## Body parameters

<ParamField body="source" type="string" default="web">
  Source type. Supported values: `web`, `googledrive`, `notion`, `zendesk`, `confluence`. Determines what the `documentIdsToAdd` and `documentIdsToRefresh` arrays contain.
</ParamField>

<ParamField body="documentIdsToAdd" type="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](/en/api-reference/register-provider-resources) or already in your workspace.
</ParamField>

<ParamField body="documentIdsToRefresh" type="array">
  Items to refresh. Same value semantics as `documentIdsToAdd`: URLs for `web`, source IDs for everything else.
</ParamField>

<ParamField body="english" type="boolean" default="true">
  Whether to apply English-specific processing.
</ParamField>

<ParamField body="baser" type="boolean" default="false">
  Whether to apply BASER processing.
</ParamField>

<Note>
  The same field names carry different value types depending on `source`. This is the most common cause of failed web imports.
</Note>

<RequestExample>
  ~~~bash Web cURL theme={null}
  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
    }'
  ~~~

  ~~~bash Provider cURL theme={null}
  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": "notion",
      "documentIdsToAdd": [
        "5d9f67a8-d853-4af4-b7ce-23ebba1245e5"
      ],
      "documentIdsToRefresh": [],
      "english": true,
      "baser": false
    }'
  ~~~

  ~~~python Python theme={null}
  import requests

  # Web import — values are URLs
  response = requests.post(
      "https://api-prod.usefini.com/v2/documents/public",
      headers={
          "Authorization": "Bearer fini_your_api_key",
          "Content-Type": "application/json",
      },
      json={
          "source": "web",
          "documentIdsToAdd": [
              "https://docs.example.com/billing/refunds",
          ],
          "documentIdsToRefresh": [],
          "english": True,
          "baser": False,
      },
  )
  data = response.json()
  ~~~

  ~~~javascript Node.js theme={null}
  // Provider import — values are document IDs from Register
  const response = await fetch(
    "https://api-prod.usefini.com/v2/documents/public",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer fini_your_api_key",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        source: "notion",
        documentIdsToAdd: ["5d9f67a8-d853-4af4-b7ce-23ebba1245e5"],
        documentIdsToRefresh: [],
        english: true,
        baser: false,
      }),
    }
  );
  const data = await response.json();
  ~~~
</RequestExample>

## Response

<ResponseField name="addedDocumentIds" type="array">
  Source IDs for items that were queued for first-time ingestion.
</ResponseField>

<ResponseField name="updatedDocumentIds" type="array">
  Source IDs for items that were queued for refresh.
</ResponseField>

<ResponseExample>
  ~~~json 202 Accepted theme={null}
  {
    "jobs": [
      {
        "id": "job_01j4fq3f0p7mef4p2j2h2vp4my",
        "documentId": "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
        "status": "PENDING"
      }
    ],
    "documents": [
      {
        "id": "4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3",
        "source": "web",
        "url": "https://help.example.com/refunds",
        "title": "Refund policy",
        "success": true,
        "changed": false,
        "linkedJobStatus": "COMPLETED",
        "linkedKnowledgeId": "7fa27325-e2f6-4420-b705-436f9106f908",
        "createdAt": "2026-07-28T08:55:32.000Z",
        "updatedAt": "2026-07-28T09:10:18.000Z"
      }
    ]
  }
  ~~~
</ResponseExample>

## Polling for completion

The response above means jobs are queued, not finished. Poll the read routes:

~~~bash Poll theme={null}
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:

| Field | Meaning |
| - | - |
| `linkedJobStatus` | `PENDING` → `IN_PROGRESS` → `COMPLETED` or `FAILED` |
| `success` | `true` when the latest run produced usable content |
| `error` | Non-empty string when the latest run failed |
| `paragraphs` | Populated after a successful run |
| `linkedKnowledgeId` | Set once the document has been linked to an article |

<Info>
  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](/en/api-reference/knowledge), and review is the recommended step before publishing.
</Info>

## Errors

<AccordionGroup>
  <Accordion title="400 Bad Request" icon="circle-exclamation">
    Common causes: unsupported `source` value, missing required fields, or passing source IDs in `documentIdsToAdd` when `source: "web"` because web imports expect URLs.
  </Accordion>

  <Accordion title="401 Unauthorized" icon="lock">
    The API key is missing, malformed, revoked, or invalid. Confirm `Authorization: Bearer fini_...` with the full key.
  </Accordion>

  <Accordion title="403 Forbidden" icon="shield-halved">
    The API key doesn't include the `write` scope, or it's scoped to a different workspace.
  </Accordion>

  <Accordion title="A web import was accepted but fails during processing" icon="link-slash">
    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.
  </Accordion>

  <Accordion title="A provider import was accepted but fails during processing" icon="plug-circle-xmark">
    The provider connection may have expired or lost permissions on the resource. Reconnect the provider in the dashboard and refresh the source.
  </Accordion>

  <Accordion title="A job stays PENDING for a long time" icon="clock">
    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.
  </Accordion>
</AccordionGroup>


## Related topics

- [List sources](/en/api-reference/list-sources.md)
- [Overview](/en/api-reference/sources.md)
- [Get source](/en/api-reference/get-source.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.