Skip to content
Sign inRequest access

REST API reference

The REST API lets an external system read feedback for a project and ingest new feedback programmatically, for an internal dashboard, a migration script, or a customer’s own tooling. It is a small, stable surface: six endpoints, key-based auth, and a documented response shape for each — with one feedback object shared by the list, create and status endpoints.

This API is authenticated with API keys, which are distinct from the widget’s tokens. Every request is re-authorized server-side against the key’s scope and tenant, and fails closed on anything missing, malformed, revoked, or out of scope.

https://api.umarker.com/api/v1

Every path below is relative to this base.

Every request needs an API key. Mint one in the dashboard under API Keys. It’s shown once at creation, and only its prefix is visible afterward. See API keys & rate limits to create and manage them.

Send the key either as a bearer token or in the X-Api-Key header (both are accepted):

Authorization: Bearer md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys carry one of two scopes, which the API enforces on every request:

  • Account-scoped keys can access every project in the account.
  • Project-scoped keys can access only their one project.

A request for a project outside the key’s scope (or in another account entirely) is rejected 403 with no data exposed. A missing, malformed, or revoked key is rejected 401.

Your working limit is per key, not per IP address, so a busy integration spends its own allowance rather than a pooled one: the default ceiling is 300 requests per minute per key. Above it sits a per-IP ceiling of 1200 requests per minute — an abuse backstop, not your working limit — and keys calling from one egress IP do share that outer number. Five busy keys behind a single office NAT or cloud gateway can reach it before any one of them has spent its own 300. Over either limit, requests are rejected with 429 Too Many Requests and a Retry-After header telling you how many seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Back off until the window resets rather than retrying tightly.

List projects

GET /projects: the projects this key can see (id + name), for discovery.

List feedback

GET /projects/{projectId}/feedback: read a project’s feedback, newest first, paginated.

Create feedback

POST /projects/{projectId}/feedback: ingest a new feedback item into a project.

Get a report

GET /feedback/{id}: full agent-ready detail for one report, plus a paste-ready markdown block.

Update status

PATCH /feedback/{id}: move a report’s status (e.g. to resolved).

Add a comment

POST /feedback/{id}/comments: leave a note on a report.

{projectId} is the numeric project ID and must be within the key’s scope; otherwise the call returns 403. {id} is a feedback ID and must belong to the key’s tenant and scope, or the call returns 404. Both must be plain positive integers. abc and 1.9 are refused the same way a missing row is, so a malformed id never becomes a second answer for someone probing the surface.

The first three endpoints (project discovery, list, and create) are documented in full below. The last three (GET/PATCH/POST on /feedback/{id}) are the agent read-and-write-back surface the MCP server is built on; they’re summarized in Agent endpoints.

Returns the project’s feedback items, ordered newest first, paginated.

GET /api/v1/projects/{projectId}/feedback?per_page=25&page=1
Authorization: Bearer md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Query parameter Type Default Notes
per_page integer 25 Items per page, clamped to 5–100 at both ends.
page integer 1 Which page to return.
curl
curl "https://api.umarker.com/api/v1/projects/7/feedback?per_page=25&page=1" \
-H "Authorization: Bearer md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

A 200 response wraps the items in data and pagination in meta:

200 OK
{
"data": [
{
"id": 12,
"comment": "Login button misaligned",
"rating": null,
"status": "new",
"priority": "high",
"source": "public",
"page_url": "https://site/checkout",
"submitter_email": "user@site.com",
"issue_url": null,
"created_at": "2026-06-30T10:00:00+00:00"
}
],
"meta": {
"current_page": 1,
"last_page": 3,
"per_page": 25,
"total": 61
}
}

The data array returns only items within the key’s scope. See The feedback object for every field.

Ingests a new feedback item into the project. The created item is stored with status: "new" and source: "api".

POST /api/v1/projects/{projectId}/feedback
Authorization: Bearer md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Field Type Required Constraints
comment string Yes Max 5000 characters.
rating string No Max 50 characters.
page_url string No Max 2048 characters, and the scheme must be http or https. The scheme is the whole check — the host and path are stored as sent. javascript:, data: and file: are refused 422 rather than quietly dropped.
email string No A valid email, max 255 characters. Stored as the submitter’s email.
metadata object No Free-form key/value context. Capped at 16 KB of JSON; anything larger is dropped.
custom_data object No Free-form application data. Capped at 16 KB of JSON; anything larger is refused 422.
curl
curl -X POST "https://api.umarker.com/api/v1/projects/7/feedback" \
-H "Authorization: Bearer md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"comment": "Checkout 500s on Safari",
"page_url": "https://site/checkout",
"email": "user@site.com",
"metadata": { "browser": "Safari 17" },
"custom_data": { "plan": "pro" }
}'

A 201 returns the created item in the same shape as the list endpoint, with source: "api":

201 Created
{
"id": 84,
"comment": "Checkout 500s on Safari",
"rating": null,
"status": "new",
"priority": null,
"source": "api",
"page_url": "https://site/checkout",
"submitter_email": "user@site.com",
"issue_url": null,
"created_at": "2026-07-01T09:15:00+00:00"
}

An ingested item fires the new_feedback event to whatever the project routes it to (Slack, Telegram, Teams, your webhook), exactly like a widget submission. See Channels & routing.

The list, create, and status-update endpoints return the same stable object:

Field Type Description
id integer The feedback item’s ID.
comment string The report text.
rating string | null An optional rating, as a string. The website snippet never sends one.
status string Lifecycle status: new, in_progress, waiting, resolved, or archived.
priority string One of none, low, medium, high, urgent. none is the stored default and is what “not prioritised” looks like, so the test for a prioritised report is priority !== 'none' — priority !== null matches every report there is. (The one place null appears is the 201 from create, which echoes the new item before the stored default is read back.)
source string Where it came from: public (the website snippet), extension (the browser extension), api (this API), or survey (a survey answer opened as a report). There is no widget value.
page_url string | null The URL the report was captured on.
submitter_email string | null The reporter’s email, when known.
issue_url string | null The linked tracker issue URL, when one exists.
created_at string ISO 8601 timestamp.

Three more endpoints let a coding agent discover projects and, after a fix ships, close the loop on a single report. They are the surface the MCP server wraps. Everything below is reachable directly over the same key auth.

GET /api/v1/projects returns the projects the key can see (an account-scoped key sees all of the account’s projects; a project-scoped key sees just its one), so an agent can resolve a project ID before listing feedback:

200 OK
{ "data": [ { "id": 7, "name": "Website" } ] }

GET /api/v1/feedback/{id} returns the full detail for one report: the reporter’s comment plus console_logs, failed_requests, metadata, custom_data, labels, and the linked issue when one exists. It also carries a markdown field that is the same paste-ready block the dashboard’s Copy report as text button produces. A report outside the key’s tenant or scope returns 404.

It also carries capture_mode: "normal" or "technical", the mode the project was in when the report was filed (null for a report filed before capture modes existed). On a Normal report, console_logs, failed_requests, breadcrumbs and technical_capture are null; on a Technical report they carry what was captured — breadcrumbs is the trail of recent clicks and route changes, and technical_capture is the full request log, exceptions, performance and environment record.

The response also carries element, which is null unless the project has element pinpointing switched on — an API-only flag the dashboard ships no control for, independent of the capture mode.

PATCH /api/v1/feedback/{id} moves a report between statuses. Send a single status field; it must be one of new, in_progress, waiting, resolved, archived. The response is the feedback object; a real change also fires an event to the project’s routed destinations — resolved when the new status is resolved, and status_change for every other move. Subscribe a channel to both, or the example below (which resolves a report) reaches nothing.

curl
curl -X PATCH "https://api.umarker.com/api/v1/feedback/84" \
-H "Authorization: Bearer md_live_…" \
-H "Content-Type: application/json" \
-d '{ "status": "resolved" }'

POST /api/v1/feedback/{id}/comments leaves a note on a report (a fix summary, a PR link). Send a body field (max 5000 characters). The comment is stored with no person attached: the 201 carries no author field at all, and the dashboard thread — the one screen that shows attribution — labels it Via the API, so your team can tell it from a colleague’s reply. A 201 returns the created comment:

201 Created
{ "id": 12, "body": "Fixed in PR #128.", "created_at": "2026-07-01T09:15:00+00:00" }

Like a comment written in the dashboard, it fires the comment event, so the team’s bell and their email hear about it, and the audit log records which key wrote it. comment is not one of the seven events a channel can subscribe to (new_feedback, assigned, mentioned, status_change, priority, resolved, issue_linked), so it does not reach Slack, Telegram, Teams or a webhook.

The API fails closed. Every error returns a JSON body with a message (and, for validation, an errors object). The auth, scope, plan and not-found messages are written in English and stay English whatever you send — those are the ones an integration branches on. Validation (422) and the maintenance 503 are translated, so a request carrying X-Locale: ar gets those two in Arabic. Branch on the status code and on the field keys inside errors, never on message text.

Status Meaning When
401 Unauthorized The key is missing (API key required.) or invalid/revoked (Invalid or revoked API key.).
403 Forbidden The plan doesn’t include API access; the account is suspended; the key’s minter is suspended or their seat is paused; the project is paused by the plan; or the requested project is out of scope or in another tenant.
404 Not found A /feedback/{id} call named a report outside the key’s tenant, scope, or history window (Not found.).
422 Unprocessable The ingest payload failed validation: the body’s errors object names each invalid field.
429 Too Many Requests The rate limit was exceeded. See Retry-After.
503 Unavailable uMarker is in a maintenance window. Retry after the Retry-After interval.
403 Forbidden
{ "message": "Project not found or not in this key's scope." }
422 Unprocessable Content
{
"message": "The comment field is required.",
"errors": {
"comment": ["The comment field is required."]
}
}
  1. Mint a project-scoped key in the dashboard under API Keys and copy the md_live_… secret (shown once).

  2. List the project’s feedback to confirm the key and scope work:

    نافذة طرفيّة
    curl "https://api.umarker.com/api/v1/projects/7/feedback" \
    -H "Authorization: Bearer md_live_…"
  3. Create a feedback item:

    نافذة طرفيّة
    curl -X POST "https://api.umarker.com/api/v1/projects/7/feedback" \
    -H "Authorization: Bearer md_live_…" \
    -H "Content-Type: application/json" \
    -d '{ "comment": "Imported from support inbox" }'
  4. Confirm it appears at the top of the list (newest first) with source: "api". If you’ve configured one, confirm your webhook received the new_feedback event.