---
title: "Trigger a manual fetch-and-ingest from an external transport"
method: POST
path: "/v1/imports/contexts/{contextId}/sources/{sourceId}/fetch"
tags: ["Ingestion"]
---

# Trigger a manual fetch-and-ingest from an external transport

`POST /v1/imports/contexts/{contextId}/sources/{sourceId}/fetch`

Lists every object matching the supplied transport coordinates (SFTP today) and streams each into the trusted-content ingestion pipeline (dedup + outbox + match-trigger), returning a per-file outcome in fetch order. The tenant is resolved from the JWT and the context/source from the path — NEVER from the body. The body carries connection coordinates plus an OPAQUE credential reference, never a secret. A transport-level fetch failure (the external endpoint is unreachable or rejects the credential) returns 503; per-file intake failures are reported in the response body without failing the batch.

## Path parameters

- `contextId` string, uuid, required — Context ID
- `sourceId` string, uuid, required — Source ID

## Request body

- FetchTriggerRequest
  - `connectOptions` object — Optional non-secret transport tuning (e.g. known_hosts, user, timeout_seconds)
  - `credentialRef` string, required — Opaque stored-credential reference (not a secret)
  - `format` string — Fallback content-format hint applied when a fetched object declares none. Accepts the namespaced FormatDescriptor key (region/family/variant) or the legacy flat aliases (cnab240, cielo_edi, ...); both resolve through the same parser registry
  - `glob` string — Optional glob filter; empty fetches all
  - `host` string, required — Remote endpoint hostname or IP
  - `kind` 'sftp' | 'https' | 's3' | 'imap' — Transport kind selecting the adapter
  - `path` string, required — Remote directory to list/fetch from
  - `port` integer, required — Remote endpoint port

## Response `202`

Accepted

- FetchTriggerResponse
  - `files` FileOutcomeResponse[], nullable, required — Per-file outcomes of the fetch-and-ingest batch, in fetch order
    - `error` string — Per-file intake failure message; empty on success
    - `ingestionJobId` string, uuid — Downstream ingestion job id; empty when the object failed intake
    - `name` string, required — Fetched object's base name
    - `transactionCount` integer, required — Number of transactions ingested from this object; zero on failure

## Other responses

- `default` — Error

---

[API](https://skmtc.net/lerian/apis/identity-plugin.md) · [All operations](https://skmtc.net/lerian/apis/identity-plugin/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lerian/identity-plugin/versions/25daba385532/schema)