Skip to main content
The Manager serves the Fetcher HTTP API. It carries 12 operations in two areas:
  • Extraction jobs under /v1/fetcher — create a job, read a job.
  • Connections under /v1/management/connections — the connection lifecycle, schema reads, connection tests, and the two product-assignment operations.
All 12 operations render under the Fetcher anchor in the API Reference. This page covers what those operations share. It does not restate their request and response shapes.
The OpenAPI documents in this portal are render sources for the reference pages. They are not client contracts, and they are not a basis for SDK generation.

​
Authentication

Fetcher accepts a JWT bearer token:
Authentication is a deployment choice. PLUGIN_AUTH_ENABLED turns the auth middleware on, and PLUGIN_AUTH_ADDRESS points it at the identity service. The Manager refuses to start when you enable auth and leave the address empty. Multi-tenant mode also requires effective authentication — the router refuses to build a tenant middleware without it. See Configuration. Every one of the 12 operations declares 401 and 403. Fetcher authorizes each request against the fetcher application, a resource (connections or fetcher), and an action that matches the HTTP method. Five routes stay outside authentication so probes keep working: /health, /readyz, /readyz/tenant/{id}, /metrics, and /version.

​
Product scope

Connection operations carry an X-Product-Name header. It names the product that owns the connection.
  • Create connection requires it. Fetcher rejects a missing, empty, or whitespace-only value.
  • List connections treats it as optional. With the header, you see one product’s connections. Without it, you see every connection in scope.
  • Fetcher lower-cases the value. It accepts letters, digits, underscores, and hyphens, up to 100 characters.
Extraction jobs do not use this header. A job names its owning product in metadata.source, which the create-job payload requires.

​
Asynchronous jobs

POST /v1/fetcher answers 202 Accepted and returns a job identifier with status pending. The Worker runs the extraction after the response. Fetcher deduplicates job requests by a request hash over a 5-minute window. A duplicate inside that window answers 200 OK and returns the existing job instead of queueing a second one. A job that already failed does not suppress a retry — you can resubmit it. To follow a job, poll GET /v1/fetcher/{id}, or subscribe to the terminal events described in Job events.

​
Pagination

Both list operations — connections and unassigned connections — use offset pagination with the same query parameters. A page response carries items, page, limit, and total.
A list request always applies a creation-date window. Send neither startDate nor endDate, and Fetcher applies the last month up to tomorrow. Older connections fall outside that window. Set both dates when you want a wider view.MAX_PAGINATION_MONTH_DATE_RANGE caps the width of that window at one month as shipped. Ask for a wider range and Fetcher moves startDate forward to fit the cap. It does not answer with an error.
Internal datasources — the ones an operator configures through DATASOURCE_{NAME}_* environment variables — appear only on page 1, ahead of the stored connections, and count toward total.

​
Filtering

The connection list accepts two filters beyond the date window.
  • type — one of POSTGRESQL, MYSQL, ORACLE, SQL_SERVER, or MONGODB. Fetcher upper-cases the value.
  • metadata.<key>=<value> — an exact match on a metadata entry you stored with the connection. For example, metadata.region=br.
The unassigned list narrows by the date window alone. It answers one question — which connections still carry no product — so it takes no type or metadata filter. Fetcher ignores an unknown query parameter rather than failing the request. Three cases still fail with FET-0405:
  • A key that starts with $, which blocks query-operator injection.
  • A key that starts with _, which blocks internal fields.
  • A key longer than 64 characters, or a value longer than 256 characters.

​
Errors

Every error answers application/problem+json and follows RFC 9457.
Match on code, not on title or detail. The codes group by range: Fetcher redacts driver-level failures at its boundary. It discards the raw database error, so a connection string, a credential, or a driver internal never reaches a caller.

​
Reading the spec from a running Manager

SWAGGER_ENABLED=true mounts a Scalar reference at /swagger/docs and the OpenAPI 3.1 document at /swagger/openapi.json and /swagger/openapi.yaml. Keep it off in production.

​
Next steps

API Reference

The 12 operations, with full request and response shapes.

Job events

React to job.completed and job.failed instead of polling.

Core concepts

Connections, schema discovery, extraction jobs, filters, and results.

Configuration

The environment variables behind auth, pagination caps, and the API surface.