Skip to main content

API conventions

Versioned base path​

Public routes live under /v1.

Session-centric design​

Most routes are scoped to a session:

/v1/sessions/{sessionId}/...

That reflects the product model: a session is the main unit of work.

Source-centric design​

Routes under /v1/sources/... manage reusable starting points and import/promotion flows.

Resource routes and action routes​

The contract mixes classic resource routes and action-style routes.

Examples of resource routes:

  • /v1/sessions
  • /v1/sessions/{sessionId}
  • /v1/sources/{sourceId}

Examples of action routes:

  • /v1/sessions/{sessionId}/commit
  • /v1/sessions/{sessionId}/restore
  • /v1/sources/{sourceId}/refresh

This is intentional. Some operations are naturally actions, not plain CRUD on a static resource.

Slash routes and colon aliases​

Some operations appear in both forms:

  • Slash form: /v1/sessions/{sessionId}/commit
  • Colon form: /v1/sessions/{sessionId}:commit

This reflects gateway/transcoding compatibility. Use the public contract as the source of truth for the exact routes your client supports.

Query parameters versus request bodies​

The API uses both patterns.

Examples:

  • Some read operations use path and query parameters.
  • Some mutation operations use JSON request bodies.
  • Some file-oriented actions use action routes because the operation is richer than simple REST CRUD.

For exact shapes, use the OpenAPI schema.

Optimistic concurrency​

Some write flows use expected hashes or similar guards.

Use them when you need to prevent accidental overwrites caused by stale client state.

Long-running and asynchronous work​

Some source-oriented flows return job-like state rather than an immediate finished result.

Examples:

  • Source import jobs under /v1/sources/{sourceId}/jobs/{jobId}

Model these as asynchronous workflows in your client.

Event and coordination endpoints​

Not every session interaction is a file mutation. The public contract also includes:

  • Message bus endpoints.
  • Knowledge cache endpoints.
  • Event feeds.
  • Approval actions.
  • Annotations.

Treat these as first-class workflow surfaces, not as secondary extras.