# Mowa full programmatic reference

> Mowa is the system of record for AI behavior: versioned prompts, typed interfaces, datasets, and usage. This document lists every public REST endpoint and MCP tool. Human-readable docs live at https://mowa.dev/developers, https://mowa.dev/developers/api, https://mowa.dev/developers/mcp, and https://mowa.dev/developers/limits.

## REST API

Base URL: https://mowa.dev/api/v1

Authentication: send an API key in the x-api-key header (or Authorization: Bearer). Keys are created in the dashboard developer page and are bound to the workspace that was active at creation time. Keys without a workspace binding are rejected with 403. Keys are rate limited (default 100 requests per minute per key).

Errors use one envelope: { "error": { "code": string, "message": string } } with status 400, 401, 402, 403, 404, 429, or 500. Free workspaces can call every endpoint; create and generate endpoints enforce plan limits and return 402 with { "error": { "code": "plan_limit", "limit": string, "message": string } } when a cap is reached.

### GET /api/v1/prompts
Lists every prompt in the key's workspace. Returns { prompts: [{ id, name, description, source, createdAt, updatedAt, liveVersion, latestVersion, latestStatus, versionCount }] }.

### POST /api/v1/prompts
Body: { name, content, description?, emoji?, color? }. Creates the prompt with version 1 as a draft and enqueues AI interface analysis. Returns 201 { id, versionId, versionNumber, analysisJobId }. Poll GET /api/v1/jobs/:jobId for suggested typed inputs and outputs.

### GET /api/v1/prompts/:id
Returns { prompt, versions: [{ ...version, inputs: [], outputs: [] }] } with every version's content, status, typed inputs, and typed outputs.

### POST /api/v1/prompts/:id/versions
Body: { content, notes? }. Adds a draft version. Returns 201 { versionId, versionNumber }.

### POST /api/v1/versions/:versionId/publish
Publishes a version live and archives the previous live version. Requires the key owner to be an owner or admin of the workspace. Returns { versionId, versionNumber, status: "live" }.

### GET /api/v1/datasets
Returns { datasets: [{ id, name, description, source, promptId, createdAt, updatedAt, rowCount }] }.

### GET /api/v1/datasets/:id?limit=100&offset=0
Returns { dataset, columns, rows, rowCount, limit, offset }. limit is 1 to 500, default 100.

### POST /api/v1/datasets/:id/rows
Body: { data: { columnName: value } }. Keys must match column names; required columns cannot be omitted. Returns 201 { id }.

### POST /api/v1/datasets/:id/generate
Body: { count (1 to 50), guidance? }. Enqueues AI row generation. Returns 202 { jobId }.

### GET /api/v1/jobs/:jobId
Returns { jobId, type: "prompt_analyze" | "dataset_generate", state, progress, result, error } for jobs started by this workspace.

### GET /api/v1/usage
Returns 30 day workspace AI usage: { windowDays, totals: { calls, inputTokens, outputTokens, images }, models: [{ model, provider, calls, inputTokens, outputTokens }] }.

## MCP server

Endpoint: https://mowa.dev/api/mcp (also served at https://mowa.dev/mcp), streamable HTTP transport.

Authorization: OAuth 2.0 with dynamic client registration. Discovery lives at https://mowa.dev/.well-known/oauth-authorization-server and https://mowa.dev/.well-known/oauth-protected-resource. During authorization you sign in and pick the workspace the connection acts as; the choice is stored per user and per OAuth client and applies to every tool call.

### Tools

- list_prompts(): every prompt in the workspace with version counts and live status.
- get_prompt(promptId): one prompt with all versions, content, typed inputs, and typed outputs.
- create_prompt(name, content, description?): creates the prompt with version 1 as a draft and enqueues AI interface analysis; returns analysisJobId.
- create_prompt_version(promptId, content, notes?): adds a draft version.
- publish_version(versionId): publishes a version live; requires owner or admin role.
- list_datasets(): every dataset with row counts.
- get_dataset(datasetId, limit?, offset?): typed columns plus a row sample (default 25 rows).
- add_dataset_row(datasetId, data): appends one row validated against the dataset columns.
- generate_dataset_rows(datasetId, count, guidance?): enqueues AI row generation, returns jobId.
- get_job_status(jobId): state, progress, and result for analysis and generation jobs.
- get_ai_usage(): 30 day workspace usage totals and per-model breakdown.
- get_billing(upgrade?): the workspace plan and usage against plan limits; with upgrade: true it returns a Stripe checkout URL for Pro (owner or admin only).
- help(): what Mowa is, every tool with a one-liner, the workspace plan limits, and documentation links.

## Notes

- Both surfaces share one permission model: workspace membership gates every read and write, and publishing requires owner or admin.
- Prompt versions move draft, in review, live, archived; only one version per prompt is live.
- Dataset generation and interface analysis run as background jobs; poll job status until state is "completed".