List projects
GET /projects: the projects this key can see (id + name), for discovery.
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/v1Every 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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxX-Api-Key: md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxKeys carry one of two scopes, which the API enforces on every request:
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 RequestsRetry-After: 30Back 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=1Authorization: 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 "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:
{ "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}/feedbackAuthorization: Bearer md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxContent-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 -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":
{ "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:
{ "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 -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:
{ "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. |
{ "message": "Project not found or not in this key's scope." }{ "message": "The comment field is required.", "errors": { "comment": ["The comment field is required."] }}Mint a project-scoped key in the dashboard under API Keys and copy the md_live_… secret (shown once).
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_…"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" }'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.