API reference
Members APIDirect link to Members API
The root URL for the endpoints below is: /v1/org/members
| Method | Endpoint | Description |
|---|---|---|
| GET | / | List members |
| POST | /invitations | Send an invitation |
| GET | /invitations | List invitations |
| DELETE | /invitations/:id | Revoke an invitation |
| PATCH | /:id | Update member role |
| DELETE | /:id | Remove a member |
API tokensDirect link to API tokens
The root URL for the endpoints below is: /v1/auth/tokens
| Method | Endpoint | Description |
|---|---|---|
| POST | / | Create an API token |
| GET | / | List API tokens |
| DELETE | /:id | Delete an API token |
Studio APIDirect link to Studio API
The root URL for the endpoints below is: /v1/studio
| Method | Endpoint | Description |
|---|---|---|
| GET | /projects | List studio projects |
| POST | /projects | Create a project |
| GET | /projects/:id | Get project detail and deploys |
| DELETE | /projects/:id | Delete a project |
| POST | /deploys | Create a deploy |
| POST | /deploys/:id/upload-complete | Confirm artifact upload |
| GET | /deploys/:id | Get deploy status |
| GET | /deploys/:id/logs | Get deploy logs |
| GET | /deploys/:id/logs/stream | Stream deploy logs (SSE) |
Server APIDirect link to Server API
The root URL for the endpoints below is: /v1/server
| Method | Endpoint | Description |
|---|---|---|
| GET | /projects | List server projects |
| POST | /projects | Create a project |
| GET | /projects/:id | Get project detail |
| DELETE | /projects/:id | Delete a project |
| PUT | /projects/:id/env | Set environment variables |
| GET | /projects/:id/env | Get environment variables |
| POST | /projects/:id/env/restart | Restart after env change |
| GET | /projects/:id/domains | List domains |
| POST | /projects/:id/domains | Add a custom domain |
| GET | /projects/:id/runtime-logs | Get runtime logs |
| POST | /projects/:id/redeploy | Trigger redeploy |
| POST | /projects/:id/always-on | Enable always-on |
| DELETE | /projects/:id/always-on | Disable always-on |
| POST | /deploys | Create a deploy |
| POST | /deploys/:id/upload-complete | Confirm artifact upload |
| GET | /deploys/:id | Get deploy status |
| GET | /deploys/:id/logs | Get deploy logs |
| POST | /deploys/:id/cancel | Cancel a queued or in-progress deploy |
| DELETE | /deploys/:id | Stop a running deploy |
Gateway APIDirect link to Gateway API
The root URL for the endpoints below is: /v1/gateway
| Method | Endpoint | Description |
|---|---|---|
| GET | /projects | List gateway projects |
| GET | /projects/:id | Get project detail |
| PATCH | /projects/:id | Update project settings |
| DELETE | /projects/:id | Delete a project |
| POST | /projects/provision | Provision a new gateway project |
| GET | /projects/:id/keys | List API keys |
| POST | /projects/:id/keys | Create an API key |
| DELETE | /projects/:id/keys/:keyId | Revoke an API key |
| GET | /projects/:id/keys/:keyId/bindings | List key-level provider bindings |
| POST | /projects/:id/keys/:keyId/bindings | Add a key-level provider binding (BYOK) |
| DELETE | /projects/:id/keys/:keyId/bindings/:provider | Remove a key-level binding |
| GET | /projects/:id/bindings | List project-level provider bindings |
| POST | /projects/:id/bindings | Add a project-level provider binding (BYOK) |
| DELETE | /projects/:id/bindings/:provider | Remove a project-level binding |
| GET | /projects/:id/usage/has-activity | Check whether project has any requests |
| GET | /projects/:id/usage/activity | Get aggregated usage activity |
| GET | /projects/:id/usage/memory-activity | Get memory-token totals over a time range |
| GET | /projects/:id/usage/logs | Get request logs |
| GET | /projects/:id/usage/logs/facets | Get log filter facets |
| GET | /projects/:id/usage/logs/:requestId | Get specific request detail |
| GET | /projects/:id/memory/threads | List threads (dashboard) |
| POST | /projects/:id/memory/threads | Create a thread (dashboard) |
| GET | /projects/:id/memory/threads/:threadId | Get thread (dashboard) |
| PATCH | /projects/:id/memory/threads/:threadId | Update thread (dashboard) |
| DELETE | /projects/:id/memory/threads/:threadId | Delete thread (dashboard) |
| POST | /projects/:id/memory/threads/:threadId/clone | Clone thread (dashboard) |
| GET | /projects/:id/memory/threads/:threadId/messages | List messages (dashboard) |
| POST | /projects/:id/memory/threads/:threadId/messages | Save messages (dashboard) |
| DELETE | /projects/:id/memory/threads/:threadId/messages | Delete messages (dashboard) |
| GET | /projects/:id/memory/threads/:threadId/observations/history | Observation history (dashboard) |
| GET | /models | List available models |
Observability feedback query APIDirect link to Observability feedback query API
The hosted feedback query API lists and analyzes feedback exported to Mastra Platform Observability. Because the API is unversioned, backwards compatibility isn't guaranteed. Rate limits, retention, and ingestion-to-query freshness aren't published contracts.
Use the root URL for your environment's data-residency region:
| Region | Root URL |
|---|---|
| United States | https://observability.mastra.ai/api/observability |
| European Union | https://observability.eu.mastra.ai/api/observability |
Telemetry stays in its residency region. Querying the other region returns no records for the environment. See Observability co-location for the environment-to-region mapping.
Authentication and project scopeDirect link to Authentication and project scope
Every request requires a platform access token. Create one in Mastra Platform, or use the token written to .env during Platform setup.
Include X-Mastra-Project-Id to limit results to one project. If you omit it, the query covers feedback in every project available to the token's organization.
curl -sS "https://observability.mastra.ai/api/observability/feedback?page=0&perPage=20&feedbackType=rating" \
-H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
-H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
Use an organization-scoped Platform access token. Gateway inference keys such as mk_* keys aren't accepted. Queries remain constrained to the token's organization even when you supply a project ID.
EndpointsDirect link to Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /feedback | List feedback records |
| POST | /feedback/aggregate | Return one aggregate value |
| POST | /feedback/breakdown | Group feedback by dimensions |
| POST | /feedback/timeseries | Bucket feedback by interval |
| POST | /feedback/percentiles | Return percentile series |
The list endpoint accepts page-mode parameters such as page, perPage, field, and direction, plus feedback filters as query parameters. It also supports delta polling with mode=delta, after, and limit. Responses contain a feedback array and page or delta metadata.
Analytics endpoints accept the same JSON request shapes and return types as the feedback reference. Analytics operate only on numeric feedback values.
curl -sS "https://observability.mastra.ai/api/observability/feedback/aggregate" \
-X POST \
-H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
-H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" \
-H "Content-Type: application/json" \
--data '{"feedbackType":"rating","feedbackSource":"user","aggregation":"avg"}' | jq
The API returns 401 for invalid credentials, 403 for organization authorization failures, and 400 for malformed query arguments or JSON bodies.
Hosted observability doesn't provide a feedback creation route. Export feedback from the application as described in Export feedback to Mastra Platform.
Gateway proxy endpointsDirect link to Gateway proxy endpoints
Visit the Gateway documentation for more details.