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

# List sources

> Paginate through every source record in the workspace, with filters on source type, ingestion status, linked knowledge, hostname, and more.

Returns source records in the workspace tied to your API key, ordered by `updatedAt` descending then `externalId` descending by default. Set `order=asc` to reverse the order. Use it to enumerate sources, inspect ingestion status, and find source IDs to pass back to [Ingest sources](/en/api-reference/ingest-sources).

<Tip>
  For the end-to-end model, see [Sources](/en/api-reference/sources). For async polling guidance, see [Ingest sources](/en/api-reference/ingest-sources#polling-for-completion).
</Tip>

<Note>
  The response field is still named `documents` because that is the current API contract. On this page, each entry is described as a source record.
</Note>

## Headers

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

## Query parameters

<ParamField query="limit" type="integer" default="50">
  Maximum number of source records to return.
</ParamField>

<ParamField query="cursor" type="string">
  Source ID to paginate from. Use the last source's `id` from the previous response to fetch the next page, or the first source's `id` to fetch the previous page.
</ParamField>

<ParamField query="direction" type="string" default="next">
  Pagination direction when a cursor is supplied. **Note the inverted mapping:** `next` moves toward *older* sources; `previous` moves back toward *newer* ones. This is because results are sorted by `updatedAt` descending.
</ParamField>

<ParamField query="order" type="string" default="desc">
  Sort direction for `updatedAt`, followed by `externalId`. Accepted values: `asc`, `desc`.
</ParamField>

<ParamField query="source" type="string">
  Optional source-type filter. Supported values: `web`, `files`, `googledrive`, `zendesk`, `notion`, `confluence`.
</ParamField>

<ParamField query="english" type="boolean">
  Optional English-processing filter.
</ParamField>

<ParamField query="success" type="array">
  Filter by ingestion outcome. Pass `true` for successful sources or `false` for failed sources. This is an array-valued query parameter.
</ParamField>

<ParamField query="id" type="string">
  Exact source ID filter.
</ParamField>

<ParamField query="title" type="string">
  Case-insensitive partial match on the source title.
</ParamField>

<ParamField query="url" type="string">
  Case-insensitive partial match on the original source URL.
</ParamField>

<ParamField query="domain" type="string">
  Filter web sources by exact hostname, for example `docs.example.com`. This parameter is valid only when `source=web`.
</ParamField>

<ParamField query="articleId" type="string">
  Filter by linked article or knowledge node ID.
</ParamField>

<ParamField query="linkedKnowledge" type="array">
  Pass `true` to return sources linked to a knowledge article or `false` to return sources without one. Supplying both values disables this filter.
</ParamField>

<ParamField query="linkedOperation" type="string">
  Filter by linked knowledge operation. Supported values: `ADD_ARTICLE_TO_FOLDER`, `UPDATE_ARTICLE`, `DO_NOTHING`.
</ParamField>

<ParamField query="changed" type="boolean">
  Return only linked sources flagged as changed. This is the key filter for the source-refresh workflow before [Bulk generate knowledge](/en/api-reference/bulk-generate-knowledge).
</ParamField>

<Note>
  The response includes `hasMore` but not a `nextCursor` field. Use the last or first source `id` from the returned array as the cursor for the next call.
</Note>

<RequestExample>
  ~~~bash cURL theme={null}
  curl --request GET \
    --url 'https://api-prod.usefini.com/v2/documents/public?limit=25&source=notion' \
    --header 'Authorization: Bearer fini_your_api_key'
  ~~~

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

  response = requests.get(
      "https://api-prod.usefini.com/v2/documents/public",
      headers={"Authorization": "Bearer fini_your_api_key"},
      params={
          "limit": 25,
          "source": "notion",
      },
  )
  data = response.json()
  ~~~

  ~~~javascript Node.js theme={null}
  const params = new URLSearchParams({
    limit: "25",
    source: "notion",
  });

  const response = await fetch(
    `https://api-prod.usefini.com/v2/documents/public?${params.toString()}`,
    {
      headers: {
        Authorization: "Bearer fini_your_api_key",
      },
    }
  );
  const data = await response.json();
  ~~~
</RequestExample>

## Response

<ResponseField name="documents" type="array">
  Array of `Document` objects.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  Whether more results exist beyond the current page.
</ResponseField>

<ResponseExample>
  ~~~json 200 OK theme={null}
  [
    {
      "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>

## Nested objects

### Document

`Document` is the wire-format object returned by the sources read routes. In the product model, each `Document` is one source record.

<ResponseField name="id" type="string">
  Source ID. Also used as the pagination cursor.
</ResponseField>

<ResponseField name="originalUrl" type="string">
  Original provider URL or web link.
</ResponseField>

<ResponseField name="title" type="string">
  Source title.
</ResponseField>

<ResponseField name="storageUrl" type="string | null">
  Internal storage URL when the source has been uploaded into Fini's storage layer.
</ResponseField>

<ResponseField name="companyId" type="string">
  ID of the workspace that owns the source.
</ResponseField>

<ResponseField name="source" type="string">
  Source type. One of `web`, `files`, `googledrive`, `notion`, `zendesk`, or `confluence`.
</ResponseField>

<ResponseField name="externalId" type="string">
  Provider-specific external identifier, or the URL itself for `web`.
</ResponseField>

<ResponseField name="english" type="boolean">
  Whether English processing is enabled for the source.
</ResponseField>

<ResponseField name="baser" type="boolean">
  Whether BASER processing is enabled for the source.
</ResponseField>

<ResponseField name="success" type="boolean">
  Whether the latest ingestion or refresh run succeeded.
</ResponseField>

<ResponseField name="error" type="string">
  Latest processing error, if any. Empty string when the last run succeeded.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 last-update timestamp. Used as the sort key.
</ResponseField>

<ResponseField name="mimeType" type="string">
  Source MIME type.
</ResponseField>

<ResponseField name="type" type="string | null">
  Provider-specific type, when available, for example Notion `page`.
</ResponseField>

<ResponseField name="linkedKnowledgeId" type="string | null">
  Linked article or knowledge node ID, if this source has already been turned into knowledge.
</ResponseField>

<ResponseField name="linkedOperation" type="string | null">
  Operation used when the source last linked into knowledge. One of `ADD_ARTICLE_TO_FOLDER`, `UPDATE_ARTICLE`, `DO_NOTHING`.
</ResponseField>

<ResponseField name="linkedReason" type="string | null">
  Additional reason metadata for the linked operation, when present.
</ResponseField>

<ResponseField name="linkedJobId" type="string | null">
  Background job ID for the latest queued ingest or refresh.
</ResponseField>

<ResponseField name="linkedJobStatus" type="string | null">
  Background job status. One of `PENDING`, `IN_PROGRESS`, `COMPLETED`, `FAILED`.
</ResponseField>

<ResponseField name="changed" type="boolean">
  Whether the latest refresh detected a meaningful change compared with the previously linked content. This is the key field for the source-refresh workflow.
</ResponseField>

<ResponseField name="paragraphs" type="array">
  Extracted paragraph payload, if the source has been processed. Can be large. Use [Get source](/en/api-reference/get-source) when you need one source and want a focused payload.
</ResponseField>

<ResponseField name="oldParagraphs" type="array">
  Previous paragraph snapshot used for change detection, when available.
</ResponseField>

## Pagination

Cursor pagination uses source IDs directly:

* pass the **last** source's `id` from the previous response with `direction=next` to move toward **older** sources
* pass the **first** source's `id` with `direction=previous` to move back toward **newer** sources

If you omit `cursor`, the API starts from the most recently updated sources.

## Errors

<AccordionGroup>
  <Accordion title="400 Bad Request" icon="circle-exclamation">
    Query parameters are invalid. Common causes: unsupported `source` value, unsupported `linkedOperation` value, malformed UUID in `id` or `articleId`.
  </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 `read` scope, or it's scoped to a different workspace.
  </Accordion>

  <Accordion title="The response is an empty documents array" icon="circle-question">
    Either the workspace has no sources matching your filters, or no sources at all. Drop filters one at a time to confirm which one is excluding results.
  </Accordion>
</AccordionGroup>


## Related topics

- [Get source](/en/api-reference/get-source.md)
- [Refresh sources](/en/api-reference/refresh-sources.md)
- [Delete sources](/en/api-reference/delete-sources.md)


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