API overview¶
Everything the DV Forge web app does goes through a public HTTP API, so you can script it: upload results from CI, pull signatures into a report, triage in bulk, or follow events live. This page covers the base URL, authentication, how to choose a project, list and error conventions, live event streams, and the main endpoint groups.
Base URL and reference¶
All endpoints are under /v1. Requests and responses are JSON unless noted
(CSV export, attachment downloads, event streams).
The complete, machine-readable description of every endpoint and schema is
the OpenAPI document at
https://api.daruur.cloud/openapi.json.
An interactive reference generated from it is at
https://api.daruur.cloud/docs.
Authentication¶
Send a bearer token on every request:
There are two kinds of token.
Your signed-in session. The web app calls the API with the session token of the person signed in. Requests made this way act as you, with your roles in each organization. Session tokens are short-lived; use them for interactive tools, not for unattended automation.
Project API tokens. For CI and scripts, a project admin creates an API
token for one project (see Projects, roles and tokens).
Tokens start with dvf_ and are shown once when created. A token sees only
its own project and has one or both scopes:
| Scope | Acts as | Typical use |
|---|---|---|
read |
viewer | Reports, dashboards, exports. |
ingest:write |
member | Uploading regression results with the CLI. |
Some actions need a person rather than a token, and refuse API tokens with 403: watching, commenting, attaching files, saving searches, listing members, notifications, creating projects, managing tokens, and listing or registering data planes. Triage changes need the triager role, which tokens don't have.
export DVF_TOKEN=dvf_... # keep it in your CI secret store
curl -s -H "Authorization: Bearer $DVF_TOKEN" \
"https://api.daruur.cloud/v1/signatures?limit=5"
Choosing a project¶
Endpoints that list or create things in a project take a project query
parameter:
- The project slug alone works when it's unambiguous across your organizations.
- Without
project, the API uses your landing project: the project nameddefaultin your oldest organization, or else the first one alphabetically.GET /v1/mereturns it asdefault_project, along with your organizations and projects. - An API token always uses its own project; naming any other project returns 404.
Endpoints that address one object by id (/v1/signatures/{id},
/v1/triage-rules/{id}) find its project from the object.
Lists¶
List endpoints return:
limit: page size, 1 to 200 (default 50).offset: how many to skip (default 0).- A
limitoroffsetout of range is a 400.
A few lists differ:
GET /v1/signatures/{id}/activitypages backward withbefore: pass the response'snext_beforeto get older events.GET /v1/notificationsreturns{"items", "unread"}and takeslimitonly.- Labels, comments, attachments and saved searches return everything at once,
with
total.GET /v1/membersreturns a plain array.
Errors¶
Errors return a status code and a JSON body with a detail message:
| Status | When |
|---|---|
| 400 | The request is understood but can't apply: a status move the lifecycle doesn't allow, a filter the language refuses, a blank comment, an image that isn't really an image, limit out of range. |
| 401 | The token is missing, malformed, expired or unknown. |
| 403 | You can see the object but your role is too low (the message names the role needed), or an API token tried something that needs a person. |
| 404 | The object doesn't exist or belongs to an organization or project you can't see. The API never answers 403 across organizations, so ids don't reveal what exists elsewhere. |
| 409 | A conflict with current state: a label name already taken, a saved search still used by a rule, a root-cause run the signature can't have. |
| 413 | The upload is too large, for example an attachment over 10 MB. |
| 422 | The body doesn't match the schema: a missing field, a wrong type, too many items (such as more than 200 ids in a bulk request). detail is a list of the problems. |
Live events¶
The API streams changes as Server-Sent Events.
Send the same Authorization header.
| Stream | What it carries | Ends |
|---|---|---|
GET /v1/events?project=… |
Every event in the project. | Never; reconnect as needed. |
GET /v1/regressions/{id}/events |
One regression's events. | When the regression is complete or aborted and its uploads are processed. |
GET /v1/runs/{id}/events |
One root-cause run's progress. | When the run finishes. |
Each event has an id, its kind as the SSE event name, and JSON data:
id: 48213
event: signature.status
data: {"id": 48213, "kind": "signature.status", "entity_type": "signature", "entity_id": "…", "payload": {"from": "untriaged", "to": "investigating", "by": "…"}, "created_at": "2026-11-17T09:12:44+00:00"}
- Pass
?after=<last id you saw>when reconnecting to resume without gaps or repeats.after=0replays from the beginning. - Quiet streams send a keepalive comment periodically. Finite streams end with
an
endevent.
Event kinds:
| Kind | Meaning |
|---|---|
regression.status |
A regression went live, completed or was aborted. |
regression.updated |
An upload to a regression was processed. |
signature.new, signature.hit, signature.recurred |
A signature's first hit in a regression; new or back after an absence. |
signature.regressed |
A resolved signature was hit again. |
signature.status, signature.assigned, signature.labeled, signature.unlabeled, signature.updated |
Triage changes (signature.updated covers bug links, classification, title and mute or waiver terms). |
signature.commented, signature.attached |
A comment or attachment was added. |
signature.merged, signature.split |
A signature was merged or split. |
signature.agent_complete, signature.agent_failed |
A root-cause run launched on the signature finished or failed. |
project.rebucket_status, project.rebucketed |
Re-bucketing progress and completion. |
run.status, scenario.status |
A root-cause run's overall and per-scenario status, plus progress events for its steps. |
Endpoint groups¶
| Group | Main endpoints | What they do |
|---|---|---|
| Health | GET /v1/health |
Service status. |
| You and your projects | GET /v1/me, GET/POST /v1/projects, GET /v1/projects/current |
Your organizations, projects and landing project; create a project. |
| API tokens | GET/POST /v1/tokens, DELETE /v1/tokens/{id} |
List, create and revoke project API tokens (project_admin). |
| Ingest | POST /v1/ingest/regressions, POST /v1/ingest/regressions/{id}/jobs, POST /v1/ingest/regressions/{id}/complete, GET /v1/ingest/batches/{id}, HEAD/PUT /v1/blobs/{sha256} |
Open a regression, upload job results and logs in batches, mark it complete, check batch processing. Used by the CLI. |
| Regressions | GET/POST /v1/regressions, GET/DELETE /v1/regressions/{id}, GET /v1/regressions/{id}/summary, GET /v1/regressions/{id}/jobs |
List and inspect regressions, their pass/fail summary and jobs. |
| Signatures | GET /v1/signatures, GET /v1/signatures/export.csv, GET/PATCH /v1/signatures/{id} |
Search (with the filter language), export, read one, edit its title or classification. |
| Merge and split | POST /v1/signatures/{id}/merge, /unmerge, /split, POST /v1/merge-suggestions/{id}/accept, /dismiss |
Combine and separate signatures; act on merge suggestions. |
| Bucketing | GET/PUT /v1/projects/current/bucketing, POST /v1/projects/current/bucketing/preview, POST /v1/projects/current/rebucket |
Bucketing settings, their preview, and re-bucketing. |
| Triage | POST /v1/signatures/{id}/status, /assign, POST/DELETE /v1/signatures/{id}/bug, PUT/DELETE /v1/signatures/{id}/labels/{label}, PUT/DELETE /v1/signatures/{id}/watch, POST /v1/signatures/bulk |
Status, assignee, bug link, labels, watching, and bulk actions (up to 200 ids). |
| Labels | GET/POST /v1/labels, PATCH/DELETE /v1/labels/{id} |
The project's labels. |
| Discussion | GET/POST /v1/signatures/{id}/comments, PATCH/DELETE /v1/comments/{id}, GET/POST /v1/signatures/{id}/attachments, GET/DELETE /v1/attachments/{id} |
Comments and attachments. |
| Timeline and summary | GET /v1/signatures/{id}/activity, GET /v1/triage/summary, GET /v1/members, GET /v1/filters/fields |
A signature's history, the project's status counts and closure, assignable members, the filter catalog. |
| Notifications | GET /v1/notifications, POST /v1/notifications/read |
Your in-app notifications. |
| Saved searches | GET/POST /v1/saved-searches, PATCH/DELETE /v1/saved-searches/{id} |
Private and shared searches. |
| Triage rules | GET/POST /v1/triage-rules, GET/PATCH/DELETE /v1/triage-rules/{id}, POST /v1/triage-rules/reorder, POST /v1/triage-rules/preview, GET /v1/rule-executions |
Rules, their order, the "would match" preview, and the run log. |
| Root-cause runs | POST /v1/signatures/{id}/root-cause, GET/POST /v1/runs, GET/DELETE /v1/runs/{id}, GET /v1/scenarios |
Launch a run from a signature (or on scenarios directly), follow and review runs. |
| Data planes | GET/POST /v1/data-planes, DELETE /v1/data-planes/{id}, PUT /v1/projects/current/data-plane, GET /v1/sim-jobs/{id}/log |
Register data planes, bind a project to one, read a job's log through it. The data plane itself uses a few further endpoints of its own. |
| Live events | GET /v1/events, GET /v1/regressions/{id}/events, GET /v1/runs/{id}/events |
Server-Sent Event streams (above). |
Roles needed for each action are listed in Permissions.