Skip to content

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

https://api.daruur.cloud

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:

Authorization: Bearer <token>

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:

?project=<org-slug>/<project-slug>
  • The project slug alone works when it's unambiguous across your organizations.
  • Without project, the API uses your landing project: the project named default in your oldest organization, or else the first one alphabetically. GET /v1/me returns it as default_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:

{"items": [...], "total": 1234}
  • limit: page size, 1 to 200 (default 50).
  • offset: how many to skip (default 0).
  • A limit or offset out of range is a 400.

A few lists differ:

  • GET /v1/signatures/{id}/activity pages backward with before: pass the response's next_before to get older events.
  • GET /v1/notifications returns {"items", "unread"} and takes limit only.
  • Labels, comments, attachments and saved searches return everything at once, with total. GET /v1/members returns a plain array.

Errors

Errors return a status code and a JSON body with a detail message:

{"detail": "tracked needs a bug reference"}
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=0 replays from the beginning.
  • Quiet streams send a keepalive comment periodically. Finite streams end with an end event.

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.