quverOS

Docs

Reference

REST API

Plain HTTP over https://tellquiver.ai/api/*. Authenticate every request with a qvr_ workspace key. Reads are GET; writes are POST/PATCH/DELETE and need a write-capable key.

auth

Authorization: Bearer qvr_xxxxxxxxxxxx

Files

Create & list

POST/api/files

write

Create a file of a configured type and populate its data in one call.

Parameter	Type	Notes
type	string · required	A file type from the workspace config (e.g. "score").
title	string	Defaults to an auto title if omitted.
data	object	Field id → value. Use an array for multi-value fields.
parent	{ id, field }	Append the new file to a parent file’s list field (a sub-item).
force	boolean	Skip dedupe when the type de-duplicates on create.

request → response

curl -X POST https://tellquiver.ai/api/files \
  -H "Authorization: Bearer $QUIVER_KEY" -H "content-type: application/json" \
  -d '{"type":"score","title":"Alice · 250","data":{"player":"Alice","value":250}}'

{ "ok": true, "file": { "id": "cmq…", "type": "score", "title": "Alice · 250" } }

GET/api/files

read

List files, optionally filtered. Add ?fields= to include data-field values per row.

Parameter	Type	Notes
type	string	Filter to one file type.
status	string · repeatable	Filter by status id(s): ?status=playing&status=ended
q	string	Title substring search.
limit	number	Max rows.
fields	csv	Include these data fields as KPIs: ?fields=value,category

response

curl "https://tellquiver.ai/api/files?type=score&fields=player,value&limit=50" \
  -H "Authorization: Bearer $QUIVER_KEY"

{ "files": [
  { "id": "cmq…", "title": "Alice · 250", "type": "score", "status": "ended",
    "kpis": [
      { "pathKey": "status", "stringValue": "ended" },
      { "pathKey": "dataFields.player", "stringValue": "Alice" },
      { "pathKey": "dataFields.value", "numericValue": 250 } ] } ] }

Files

Read, update & delete a file

GET/api/files/:id

read

Fetch one file with its full data and KPIs.

response

{ "ok": true, "file": {
  "id": "cmq…", "title": "Alice · 250", "type": "score", "status": "ended",
  "data": "{\"player\":\"Alice\",\"value\":250}",
  "kpis": [ … ] } }

POST/api/files/:id/data

write

Set one or more data fields (and optionally the title). Writes through the real KPI path, so metrics update immediately.

Parameter	Type	Notes
fields	object · required	Field id → new value. Batch-applied in one mutation.
title	string	Optionally rename the file.

request

curl -X POST https://tellquiver.ai/api/files/$ID/data \
  -H "Authorization: Bearer $QUIVER_KEY" -H "content-type: application/json" \
  -d '{"fields":{"value":600,"category":"hard"},"title":"Alice · 600"}'

POST/api/files/:id/status

write

Move a file to a status in its workflow (e.g. playing → ended).

request

curl -X POST https://tellquiver.ai/api/files/$ID/status \
  -H "Authorization: Bearer $QUIVER_KEY" -H "content-type: application/json" \
  -d '{"status":"ended"}'

{ "ok": true, "fileId": "cmq…", "status": "ended" }

DELETE/api/files/:id

write

Permanently delete a file.

request

curl -X DELETE https://tellquiver.ai/api/files/$ID \
  -H "Authorization: Bearer $QUIVER_KEY"
# → { "ok": true }

Metrics

Read computed values

You declare metrics in config (count, sum, max, grouped breakdowns, derived). The engine computes them — you just read the value.

GET/api/metrics

read

With ?id= returns one metric (including its grouped breakdown); without, returns a snapshot of all metrics + a catalog.

Parameter	Type	Notes
id	string	A metric id from config. Omit for the full snapshot.

single metric

curl "https://tellquiver.ai/api/metrics?id=leaderboard" \
  -H "Authorization: Bearer $QUIVER_KEY"

{ "metric": {
  "id": "leaderboard", "metric": 250,
  "breakdown": [
    { "key": "client-abc", "value": 250 },
    { "key": "client-def", "value": 175 } ] } }

Discovery

Search, activity & orientation

GET/api/files/search

read

Free-text recall over titles and data-field values.

response

curl "https://tellquiver.ai/api/files/search?q=Alice&type=score&limit=5" \
  -H "Authorization: Bearer $QUIVER_KEY"
# → { "results": [ { "id": "…", "title": "Alice · 250", "type": "score", "status": "ended" } ] }

GET/api/activity

read

Recent changes across the workspace (field, value, actor, time).

request

curl "https://tellquiver.ai/api/activity?limit=20" -H "Authorization: Bearer $QUIVER_KEY"

GET/api/orient

read

A one-call bootstrap bundle — purpose, singletons, active files, per-type counts, recent activity. Built for agents starting cold.

request

curl "https://tellquiver.ai/api/orient" -H "Authorization: Bearer $QUIVER_KEY"

Workspace

Inspect the workspace & its config

GET/api/workspace

read

Workspace metadata; ?include=config returns the full schema (types, fields, statuses, metrics, views).

Parameter	Type	Notes
include	string	config · apikeys · secrets · variables

response

curl "https://tellquiver.ai/api/workspace" -H "Authorization: Bearer $QUIVER_KEY"
# → { "workspace": { "id": "…", "name": "Quiver Archer", "configId": "personal.leaderboard", "userCount": 1 } }