Skip to main content

Underlay sources

Sources are reusable starting points for sessions.

If sessions are the working copies, sources are the durable baselines they may start from or promote into.

Core routes​

Key source routes include:

  • POST /v1/sources
  • GET /v1/sources
  • GET /v1/sources/{sourceId}

Use these to create, enumerate, and inspect reusable sources.

Refresh and import​

Source lifecycle routes include:

  • /v1/sources/{sourceId}/refresh
  • /v1/sources/{sourceId}/startImport
  • /v1/sources/{sourceId}/jobs/{jobId}

Use these when a source needs to ingest new content or when import is asynchronous and should be tracked as a job.

Promote a session into a source​

The public contract includes:

  • /v1/sources/{sourceId}/promoteSession

Use this when a session’s result should become a reusable future baseline.

Design guidance​

Use sources when you need:

  • Repeatable starting points.
  • Reusable templates or baselines.
  • A clean distinction between temporary workspaces and durable origins.

Use sessions when you need:

  • Active mutable work.
  • Review branches.
  • Per-user or per-task isolation.