> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mithunai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync a source into its collection now

> Queue an ingestion run. It returns 202 as soon as the job is recorded, before anything is ingested, and is idempotent while a run for that source is active.

Returns `202` as soon as the job is recorded. Nothing has been ingested yet. Poll [Get a job](/api-reference/knowledge/get-job) with the returned `id`, or [Get a source's latest job](/api-reference/knowledge/get-source-job), until `is_active` is `false`.

Syncing is idempotent while a run is active. If the source already has a `pending`, `queued` or `running` job, you get that job back with `202` and no second run starts. Retrying a request is therefore safe.

A sync always re-reads the whole source, even when the source version has not changed. Documents whose content is unchanged are counted as `documents_unchanged` and are not re-indexed. If the source's collection is archived, the sync is accepted and the job ends `failed`.

Syncing requires a role that can add documents. A read-only member receives `403`. An unknown ID, a malformed ID, or another organization's source returns `404`. See [Ingestion](/knowledge/ingestion).

<ParamField path="source_id" type="string" required>
  Source ID (a UUID).
</ParamField>

## Response

Returns `202` with the job. A new job has `status` `queued`, `trigger` `manual` and all counters at `0`.

<ResponseField name="id" type="string" required>
  Job ID (a UUID).
</ResponseField>

<ResponseField name="collection_id" type="string" required>
  Collection being ingested into.
</ResponseField>

<ResponseField name="source_id" type="string" required>
  Source being ingested.
</ResponseField>

<ResponseField name="status" type="string" required>
  `pending`, `queued`, `running`, `succeeded`, `partial`, `failed`, `cancelled` or `skipped`. See
  [Get a job](/api-reference/knowledge/get-job) for what each means.
</ResponseField>

<ResponseField name="trigger" type="string" required>
  `manual`, `scheduled` or `api`.
</ResponseField>

<ResponseField name="source_version" type="string | null" required>
  Source version the run read, such as a commit SHA. `null` until the run starts.
</ResponseField>

<ResponseField name="is_active" type="boolean" required>
  `true` while the status is `pending`, `queued` or `running`.
</ResponseField>

<ResponseField name="attempt" type="integer" required>
  Which attempt this is, starting at `1`.
</ResponseField>

<ResponseField name="max_attempts" type="integer" required>
  Total attempts allowed.
</ResponseField>

<ResponseField name="queued_at" type="string | null" required>
  ISO 8601 timestamp, in UTC, when the current attempt was queued.
</ResponseField>

<ResponseField name="started_at" type="string | null" required>
  ISO 8601 timestamp, in UTC, when the current attempt started.
</ResponseField>

<ResponseField name="finished_at" type="string | null" required>
  ISO 8601 timestamp, in UTC, when the job ended.
</ResponseField>

<ResponseField name="next_attempt_at" type="string | null" required>
  ISO 8601 timestamp, in UTC, before which a queued retry will not start.
</ResponseField>

<ResponseField name="error_code" type="string | null" required>
  Stable error code when the run failed. Otherwise `null`.
</ResponseField>

<ResponseField name="error_message" type="string | null" required>
  Readable description of the failure. Otherwise `null`.
</ResponseField>

<ResponseField name="counters" type="object" required>
  `documents_discovered`, `documents_ingested`, `documents_unchanged`, `documents_skipped`,
  `documents_failed`, `documents_deleted`, `chunks_written` and `bytes_fetched`, all integers. See
  [Get a job](/api-reference/knowledge/get-job).
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST "$MITHUNAI_URL/arukz/api/v1/knowledge/sources/5d1e7a90-3c4b-4f2a-8e61-7b9c0d2f4a13/sync" \
    --header "Authorization: Bearer $MITHUNAI_API_KEY"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os, requests

  source_id = "5d1e7a90-3c4b-4f2a-8e61-7b9c0d2f4a13"
  response = requests.post(
      f"{os.environ['MITHUNAI_URL']}/arukz/api/v1/knowledge/sources/{source_id}/sync",
      headers={"Authorization": f"Bearer {os.environ['MITHUNAI_API_KEY']}"},
      timeout=60,
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const sourceId = '5d1e7a90-3c4b-4f2a-8e61-7b9c0d2f4a13'
  const response = await fetch(
    `${process.env.MITHUNAI_URL}/arukz/api/v1/knowledge/sources/${sourceId}/sync`,
    {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.MITHUNAI_API_KEY}` },
    },
  )
  console.log(await response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "9a4c2e71-6b0d-4f38-a5e2-1c7d8f3b6e40",
    "collection_id": "0b6f2c14-8a3d-4e91-9c77-2f5b1d0a4e88",
    "source_id": "5d1e7a90-3c4b-4f2a-8e61-7b9c0d2f4a13",
    "status": "queued",
    "trigger": "manual",
    "source_version": null,
    "is_active": true,
    "attempt": 1,
    "max_attempts": 3,
    "queued_at": "2026-09-24T10:20:05.127004+00:00",
    "started_at": null,
    "finished_at": null,
    "next_attempt_at": null,
    "error_code": null,
    "error_message": null,
    "counters": {
      "documents_discovered": 0,
      "documents_ingested": 0,
      "documents_unchanged": 0,
      "documents_skipped": 0,
      "documents_failed": 0,
      "documents_deleted": 0,
      "chunks_written": 0,
      "bytes_fetched": 0
    }
  }
  ```

  ```json 403 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "authorization_error", "message": "You do not have permission to perform this action." }
  ```

  ```json 404 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "not_found", "message": "The knowledge source was not found." }
  ```
</ResponseExample>