Integration API Reference — Quemsi /api/v1

Base URL is your Quemsi host (production is https://quemsi.com). Create a token first: Create API tokens. Integration tokens cannot call the interactive /api/** UI surface. Human JWTs may call /api/v1, but pipelines should use qsk_ tokens.

Authentication

Authorization: Bearer qsk_...

Scopes: snapshot, restore, read (default all three). If the token is bound to an agent, agent in the JSON body must be that agent’s name.

Endpoints

Method	Path	Scope	Purpose
POST	`/api/v1/snapshots`	`snapshot`	Backup: `data` + `agent` (+ `flow` if several forward flows) + `tags`
POST	`/api/v1/restores`	`restore`	Restore: `agent` + `targetDatasource` + `versionId` or `data` + tags
GET	`/api/v1/executions/{id}`	`read`	Poll until `SUCCESS` / `FAILED` / `SKIPPED`
GET	`/api/v1/restore-actions`	`read`	Discover the latest tagged restore cards (same idea as the Restore page)

Agent is a name in the JSON body, not a quemsi-agent-id header. The target agent must be ONLINE. Restore overwrites the target database; existing objects are dropped or cleared, then the snapshot is loaded.

Snapshot body

data (required) — data item name
agent (required) — agent name
flow — forward flow name; required if that data has more than one forward flow on the agent
tags — object of tag name to value (AND when you restore later)
descript — optional description on the version

curl -sS -X POST "$QUEMSI_URL/api/v1/snapshots" \
  -H "Authorization: Bearer $QUEMSI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "shopping-cart",
    "agent": "ci-staging",
    "tags": { "release": "1.42.0", "purpose": "pre-deploy" },
    "descript": "pre-deploy snapshot"
  }'

Restore body

agent (required) — agent that owns the target database
targetDatasource (required) — datasource name on that agent
versionId — restore that version, or omit and pass data plus tags to use the latest matching version
data + tags — required together when versionId is omitted; tags must not be empty

curl -sS -X POST "$QUEMSI_URL/api/v1/restores" \
  -H "Authorization: Bearer $QUEMSI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "shopping-cart",
    "agent": "ci-staging",
    "targetDatasource": "app-db",
    "tags": { "use-case": "e2e-baseline" }
  }'

Poll execution

Both POSTs return a flow execution. Read id and poll status. Values are SCHEDULED, RUNNING, SUCCESS (UI label “Completed”), FAILED, and SKIPPED.

curl -sS "$QUEMSI_URL/api/v1/executions/$EXECUTION_ID" \
  -H "Authorization: Bearer $QUEMSI_TOKEN"

Treat SUCCESS as pass. Fail the job on FAILED or SKIPPED. Do not start tests or deploy while status is still SCHEDULED or RUNNING.

Restore-actions query tags

Repeat the tag query parameter. Each value is name or name=value. All of them must match (AND).

curl -sS "$QUEMSI_URL/api/v1/restore-actions?tag=app=quemsi&tag=site=local" \
  -H "Authorization: Bearer $QUEMSI_TOKEN"

Wrong: ?tag=app=quemsi&site=local — only tag is bound. site is ignored, so you filter on app=quemsi alone.

Leave the value empty (tag=use-case) to match every value of that tag name. Legacy tagName=use-case is the same as a name-only filter. If you pass neither tag nor tagName, the default filter is tag name use-case.

API reference