testosaurusdocs
Browse docs
On this page

API reference

Testo typing

Most projects never touch anything below init(). The rest of this page exists for the ones that script their own submissions or wire the widget into a test pipeline.

init(options)

Call once after the script tag. Idempotent: repeated calls are no-ops while a widget is mounted, and two copies of the bundle on one page still give one widget.

ts
Testosaurus.init({
  endpoint?: string,             // optional — defaults to 'https://testosaurus.dev'
  apiKey: string,                // required — public app token; identifies the project
  position?: 'bottom-right' | 'bottom-left',  // default: the project's widget setting
  showWelcome?: boolean          // false never shows the first-visit welcome bubble
});

If apiKey is missing or empty, init logs [testosaurus] init requires an apiKey; widget not mounted and does not mount the widget. The queue stub also accepts calls made before the bundle loads, so load order doesn't matter. Other console messages, and what to do about them, are listed in Troubleshooting.

open()

Open the mounted widget from your own application control with Testosaurus.open(). Call it after initialization completes. The return value is true when a mounted widget receives the request, or false when none is mounted.

This enters the same flow as the launcher. It does not grant capture consent, change the selected project or submit a report. See the custom-button example.

Report shape

A submitted report carries:

  • message — the tester's text.
  • context — url, title, userAgent, viewport, language and console (up to 20 recent warnings and errors), cleaned of secrets before it is sent. Two more keys appear when an attachment was uploaded: screenshotRef and replayRef. screenshotStatus records ok, capture_failed, too_large or upload_failed for the screenshot.
  • screenshot — optional, only with screenshot consent, uploaded first and referenced by screenshotRef.
  • replay — optional, only with replay consent, referenced by replayRef.
  • distilled fields — title, category, severity, summary, steps (reproduction steps), suggested_cause (the suggested cause: a hypothesis, present only when known) and provider (the model that answered), added asynchronously. See Reports & distillation.

Endpoints

POST /api/submit

Stores a report and enqueues distillation. Header x-api-key must be a valid app token for the project, and the page's host must be one of the project's allowed addresses; otherwise the call is rejected with 403 and code: "domain_mismatch". Every rejection carries an error message and a machine-readable code.

A new report answers 201 with { id, ok: true }. Send a unique clientSubmissionId (a UUID) with each report to make resends safe: a report whose clientSubmissionId is already stored answers 200 with the id of the first copy, and nothing is stored, counted, queued or announced a second time.

Reports are rate limited. One visitor (an app token plus a client address; IPv6 addresses count per /64) may send 5 reports a minute, and one token accepts 10 reports a minute and 500 per UTC day. Past a limit the call answers 429 with code: "rate_limited" or "daily_limit"; wait and send again. A used-up monthly allowance answers 429 with code: "balance_exhausted", which does not clear until the allowance resets or credit is added.

PUT /api/screenshot

Uploads a screenshot to storage and returns { key }. The body must be a PNG image of at most 2 MB; any other format, such as JPEG or WebP, is refused with 400. Pass the key on the submit call to attach it.

PUT /api/replay

Uploads session-replay JSON (at most 10 MB) and returns { key }. The body must be a JSON array, so it has to start with [; anything else is refused with 400. Same attach-on-submit rule.

Both upload endpoints answer 429 with code: "rate_limited" when a visitor or the token uploads too fast, and when a visitor has too many uploads that no report has claimed yet (30 objects or 30 MB an hour; the whole project allows 300 objects or 300 MB). Attach uploads to a report promptly. An upload that exceeds the workspace's storage quota answers 413.

Status codes

  • 2xx — stored. The widget shows its success state.
  • 4xx — rejected (bad token, disallowed origin, an unusable report). The widget logs the status, the code and a hint to the console and does not queue the report; the tester's text stays in the panel so it can be sent again.
  • 5xx / timeout / offline — the report is queued locally and retried when the connection returns and on the next page load. See Offline queue.

An attachment that cannot be captured, is too large or fails to upload is left out and the report is still delivered; the report records the screenshot's reason in screenshotStatus and the dashboard shows it.

Dashboard API

Endpoints the widget never calls. All of them need your signed-in dashboard session, not an app token.

GET /api/projects/:id/export

A portable copy of one project in a single JSON download: its settings, every submission with its raw text, context and distilled fields, and a manifest of the stored media. You can take it whenever you want — no lock-in. It is not a backup: it leaves out the screenshot and replay files themselves (the manifest lists where to fetch each one while it is still stored), shared-issue groupings and their history, coding-run history, tokens and the webhook secret. Owner only; the response carries content-disposition: attachment, so a plain browser link triggers the download.

json
{
  "version": 1,
  "exportedAt": "2026-09-12T09:30:00.000Z",
  "project": {
    "id": "…",
    "name": "Web app",
    "createdAt": "…",
    "domains": ["app.example.com"],
    "archived": false,
    "notifications": { "notifyNew": true, "notifyHighSeverity": true, "notifyFailedDistill": true },
    "settings": {
      "aiSettings": null,
      "distillEnabled": true,
      "showBranding": true,
      "widgetTheme": null,
      "webhookUrl": null,
      "turnstile": { "sitekey": "…", "source": "auto", "mode": "invisible" },
      "githubRepo": null,
      "fixMerges": { "detect": true, "markShipped": false },
      "githubLabels": [],
      "linearTeamId": null
    }
  },
  "submissions": [
    {
      "id": "…",
      "clientKey": "…",
      "raw": "Checkout button does nothing on Safari",
      "context": { "url": "https://app.example.com/checkout", "title": "Checkout", "userAgent": "Mozilla/5.0 (Macintosh) … Safari/605.1.15", "viewport": { "width": 1280, "height": 800 }, "language": "en", "console": [] },
      "distillation": { "title": "…", "category": "bug", "severity": "high" },
      "distillState": "done",
      "distillError": null,
      "status": "new",
      "raisedRef": null,
      "createdAt": "…"
    }
  ],
  "media": [
    {
      "key": "…",
      "kind": "screenshot",
      "size": 84213,
      "contentType": "image/png",
      "createdAt": "…",
      "submissionId": "…",
      "fetchPath": "/api/screenshot/…",
      "available": true
    }
  ]
}

Each media entry is a stored screenshot (image/png) or replay (application/json). Fetch the bytes through fetchPath with your dashboard session; it is null for uploads with no submission attached. available is false once the blob has been purged, and size and contentType come from the stored object when it still exists.

PATCH /api/usage/settings/:resource

Sets the overage policy and alert threshold for one metered resource: submissions, storage, ai, or seats. Workspace owner only; unknown resources get a 422. Both body fields are optional:

json
{ "overageAllowed": true, "alertThresholdPct": 90 }

alertThresholdPct is an integer from 10 to 100 — the share of the included allowance where usage alert emails fire. overageAllowed lets usage continue past the included limit at the published rate, drawn from your prepaid balance. It takes effect only when your plan supports overage (Pro or Enterprise) and you've opted in for that resource; otherwise usage stops at the included limit. The response is the updated usage row for the resource — the same shape the billing & usage page renders.

GET /api/models

The model catalog behind the model picker on settings → ai analysis: the chat models Testosaurus offers through the Vercel AI Gateway, each with its input and output price per token in micro-euros and its vision and structured-output flags, plus the server default model — the one used when a project leaves its Default role unset.

PATCH /api/projects/:id

Updates project settings. AI model control rides on the aiSettings object: an optional default model (null falls back to the server default), an optional vision model, custom roles — each a slug, a label, and a model — and categories, mapping the four distilled categories (bug, confusing, idea, other) to role slugs. Every model id is validated against the model catalog; an unknown id is rejected with a 400.

json
{
  "aiSettings": {
    "default": "openai/gpt-4o-mini",
    "vision": null,
    "roles": [
      { "slug": "bug-investigator", "label": "Bug investigator", "model": "anthropic/claude-sonnet-4" }
    ],
    "categories": { "bug": "bug-investigator" }
  }
}
Something unclear?Let us know