Skip to main content

​
API Reference

The MutagenT REST API provides programmatic access to all platform features.

​
Base URL

https://api.mutagent.io

​
Authentication

All API requests require authentication. MutagenT supports two authentication methods: 
curl -H "x-api-key: your_api_key_here" \
  https://api.mutagent.io/api/prompts
API Key scoping determines which headers are required. Workspace-scoped keys require no additional headers. Organization-scoped keys require x-workspace-id. User-scoped keys require both x-workspace-id and x-organization-id. See API Keys for details.

​
Endpoints Overview

All endpoints are prefixed with /api.

​
Prompts

MethodEndpointDescription
GET/api/promptList all prompts
POST/api/promptCreate a new prompt
GET/api/prompt/:idGet prompt by ID
PATCH/api/prompt/:idUpdate prompt
DELETE/api/prompt/:idDelete prompt
POST/api/prompt/:id/versionsCreate new version
POST/api/prompt/:id/playgroundRun prompt in playground

​
Datasets

MethodEndpointDescription
GET/api/prompts/datasetsList all datasets
GET/api/prompt/:id/datasetsList datasets for a prompt
POST/api/prompt/:id/datasetsCreate dataset for a prompt
GET/api/prompts/datasets/:idGet dataset by ID
PATCH/api/prompts/datasets/:idUpdate dataset
DELETE/api/prompts/datasets/:idDelete dataset
POST/api/prompts/datasets/:id/cloneClone dataset
GET/api/prompts/datasets/:id/exportExport dataset
GET/api/prompts/datasets/:id/itemsList dataset items
POST/api/prompts/datasets/:id/itemsAdd single item
POST/api/prompts/datasets/:id/items/bulkBulk add items

​
Evaluations

MethodEndpointDescription
GET/api/prompts/evaluationsList evaluations
POST/api/prompts/evaluationsCreate evaluation
GET/api/prompts/evaluations/:idGet evaluation by ID
POST/api/prompts/evaluations/:id/runRun evaluation
GET/api/prompts/evaluations/:id/resultGet evaluation results

​
Optimization

MethodEndpointDescription
POST/api/prompt/:id/optimizeStart optimization job
GET/api/optimizationList optimization jobs
GET/api/optimization/:idGet job status
GET/api/optimization/:id/progressGet score progression
POST/api/optimization/:id/pausePause job
POST/api/optimization/:id/resumeResume job
POST/api/optimization/:id/cancelCancel job

​
Traces

MethodEndpointDescription
GET/api/tracesList traces
POST/api/tracesIngest trace data
GET/api/traces/:idGet trace by ID
POST/api/traces/otlpOTLP bridge endpoint

​
Agents

MethodEndpointDescription
GET/api/agentsList agents
POST/api/agentsCreate agent
GET/api/agents/:idGet agent by ID
PATCH/api/agents/:idUpdate agent
DELETE/api/agents/:idDelete agent

​
Organizations and Workspaces

MethodEndpointDescription
GET/api/organizationsList organizations
GET/api/workspacesList workspaces
GET/api/workspaces/:idGet workspace by ID

​
Providers

MethodEndpointDescription
GET/api/providersList configured providers
GET/api/providers/:idGet provider by ID

​
API Keys

MethodEndpointDescription
GET/api/api-keysList API keys
POST/api/api-keysCreate API key
DELETE/api/api-keys/:idRevoke API key

​
Rate Limits

PlanRequests/minuteRequests/day
Free601,000
Pro30010,000
EnterpriseCustomCustom

​
Response Format

All responses are JSON: 
{
  "data": { ... },
  "meta": {
    "requestId": "req_xxxx",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

​
Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid prompt ID",
    "details": { ... }
  },
  "meta": {
    "requestId": "req_xxxx"
  }
}

​
Common Status Codes

CodeDescription
200Success
201Created
400Bad Request
401Unauthorized
403Forbidden
404Not Found
429Rate Limited
500Server Error

​
SDKs

We recommend using our official SDKs instead of direct API calls:

TypeScript SDK

Type-safe TypeScript/JavaScript SDK

Python SDK

Python SDK (coming soon)

​
OpenAPI Specification

The full OpenAPI specification is available at: 
https://api.mutagent.io/docs/json