API Reference

The UserDispatch REST API lets you submit feedback, manage apps, and query submissions programmatically. For most use cases, connecting via MCP is easier than calling the REST API directly.

Base URL

https://userdispatch.com/api

Authentication

UserDispatch uses two types of authentication depending on the endpoint:

App API key (for submissions)

Used for the submissions endpoint. Pass your app's API key in the X-API-Key header:

POST /api/v1/submissions
X-API-Key: pk_your-app-api-key
Content-Type: application/json

Bearer token (for admin endpoints)

Used for all admin endpoints. Pass your ud_ token in the Authorization header:

GET /api/v1/admin/submissions
Authorization: Bearer ud_your-admin-token

Submit feedback

POST/api/v1/submissions

Request body (JSON)

Field	Type	Required	Description
type	string	Yes	`feedback`, `question`, `bug_report`, or `automated_log`
message	string	No	Feedback message (max 10,000 chars)
email	string	No	Submitter email (max 320 chars)
name	string	No	Submitter name (max 200 chars)
subject	string	No	Subject line (max 500 chars, bug reports)
rating	number	No	Star rating, 1–5 (feedback type)
metadata	object	No	Arbitrary JSON metadata (max 50KB serialized)

Example

Request

POST /api/v1/submissions HTTP/1.1
Host: userdispatch.com
X-API-Key: pk_your-app-api-key
Content-Type: application/json

{
  "type": "bug_report",
  "email": "user@example.com",
  "subject": "Checkout page crashes",
  "message": "Page freezes when clicking the Pay button on Safari.",
  "metadata": {
    "page": "/checkout",
    "browser": "Safari 17"
  }
}

Response (201)

{
  "id": "sub_abc123",
  "type": "bug_report",
  "status": "new",
  "created_at": "2026-02-28T12:00:00Z"
}

File uploads are supported via multipart/form-data. Include files as form parts alongside a json part for the submission body. Maximum request body size is 55MB.

Admin endpoints

All admin endpoints require Bearer token authentication. These are the same endpoints the MCP server uses internally.

Method	Endpoint	Description
GET	/api/v1/admin/submissions	List submissions (with query filters)
GET	/api/v1/admin/submissions/:id	Get submission details
PATCH	/api/v1/admin/submissions/:id	Update submission status
DELETE	/api/v1/admin/submissions/:id	Delete submission
POST	/api/v1/admin/submissions/:id/replies	Reply to submission
GET	/api/v1/admin/apps	List all apps
POST	/api/v1/admin/apps	Create app
PATCH	/api/v1/admin/apps/:id	Update app
DELETE	/api/v1/admin/apps/:id	Delete app
POST	/api/v1/admin/apps/:id/rotate-key	Rotate app API key
GET	/api/v1/admin/org	Get organization details
PATCH	/api/v1/admin/org	Update organization
GET	/api/v1/admin/org/members	List members
POST	/api/v1/admin/org/members	Invite member
PATCH	/api/v1/admin/org/members/:id	Update member
DELETE	/api/v1/admin/org/members/:id	Remove member
GET	/api/v1/admin/stats	Get submission statistics

Query parameters

The list submissions endpoint supports these query parameters:

Parameter	Type	Default	Description
app	string	—	Filter by app slug
type	string	—	Filter by submission type
status	string	—	Filter by status (new, in_progress, resolved, closed)
since	date	—	Filter from date (YYYY-MM-DD)
until	date	—	Filter to date (YYYY-MM-DD)
search	string	—	Full-text search (max 200 chars)
limit	number	50	Results per page (1–200)
offset	number	0	Pagination offset
sort	string	created_at	Sort field (created_at, updated_at, rating)
order	string	desc	Sort order (asc, desc)

Error handling

Error responses use a consistent JSON format:

{
  "error": "Validation failed",
  "details": "type: Required"
}

Common error codes

Code	Description
400	Bad request — validation failed or malformed body
401	Unauthorized — missing or invalid API key/token
404	Resource not found
409	Conflict — duplicate slug or name
429	Rate limited — too many requests

Rate limits

Submissions: 10-second deduplication window per API key (same type + message = rejected)
Admin API: Standard rate limiting per token
Request size: 55MB maximum content length