Core concepts

Siphon has a small vocabulary. Learn these four nouns and the rest of the docs read easily.

Connector

A connector is a declarative description of a source API — a ConnectorSpec. It defines how to authenticate, what to fetch, how to paginate, how to enrich and transform records, and what to deliver. It is versioned: each published version is immutable and checksummed, so a connection always runs an exact, known spec.

The connector spec is the product. The engine, API, and UI only author, execute, or observe a spec.

A connector is org-scoped, except builtin connectors (which have no org). You author one in the visual Connector Builder or by importing YAML/JSON — no per-connector code.

Connection

A connection is one customer's live instance of a connector. It pins a specific published spec version and carries:

• params — non-secret configuration declared by the spec's connectionParams (a base URL, an account id, a page size).
• secrets — API keys, passwords, tokens — envelope-encrypted at rest and redacted from every log.
• an optional spec override — a partial spec merged onto the pinned base so this one customer can differ without forking.

A connection moves through a lifecycle: pending → active → (paused | error). Only active connections sync.

Resource

A connector defines one or more resources — the distinct things it can pull (e.g. deals, invoices, contacts). Each resource has its own fetch, enrichment, transform, validation, output columns, and sync policy (full vs incremental, and how change filtering works). A sync always targets one resource of one connection.

Run

A run is a single execution of a resource sync. It is a durable, crash-resumable workflow that pages through the source and — per page — change-filters, enriches, transforms, validates, and delivers. A run records:

• stats — pages, records in, skipped, records out, quarantined, errors.
• a redacted call log — every HTTP request/response, grouped by pipeline stage.
• run errors and quarantined records for anything that didn't pass.
• the advanced watermark and any updated record fingerprints.

Runs are observable in the Run Inspector, which can also diagnose a failure with AI.

How they relate

Connector (spec, versioned + immutable)
  └── Connection (pins a version; params + encrypted secrets + optional override)
        └── Run (one execution of one Resource's sync)
              └── delivers to a Destination

A trigger starts a run — manual (a button or API call), schedule (cron), webhook, or backfill. Every trigger takes the same durable path, so a scheduled run and a manual run behave identically.