Endpoint reference

Every `/api/v1` endpoint with method, query params, an example request, and the actual response shape returned.

Updated 2026-04-25 · By Jon Lasley

Five GET endpoints, all wrapped by the same authenticator. Path-only resources return a Prompt or Version; list endpoints return summaries plus pagination meta. Wrong-tenant lookups always return 404 NOT_FOUND rather than 403, so the API never confirms whether a resource exists in another workspace.

All endpoints at a glance

Method	Path	Returns
`GET`	`/api/v1/prompts`	List of prompt summaries (paginated)
`GET`	`/api/v1/prompts/{id}`	Full prompt with metadata and tags
`GET`	`/api/v1/prompts/{id}/resolved`	Prompt with fragments inlined and variables substituted
`GET`	`/api/v1/prompts/{id}/versions`	List of version summaries (paginated)
`GET`	`/api/v1/prompts/{id}/versions/{version}`	Full version row with content

List prompts

Returns a paginated list of prompt summaries for the calling key's workspace. Archived prompts (is_archived = true) are excluded; ordered by updated_at DESC.

Query param	Type	Description
`page`	integer	Default `1`.
`per_page`	integer	Default `20`, max `100`.
`folder_id`	UUID	Filter to one folder. Invalid UUID returns 400.
`tag`	string	Filter by tag name (e.g. `production`), not slug.
`type`	enum	One of `system`, `user`, `assistant`, `template`, `few-shot`, `chain-of-thought`. Other values return 400.

curl -H "Authorization: Bearer pa_live_..." \
  "https://promptassay.ai/api/v1/prompts?page=1&per_page=50&tag=production"

List prompts tagged `production`, page 1, 50 per page.

{
  "data": [
    {
      "id": "0a1b2c3d-...",
      "title": "Support triage classifier",
      "description": "Classifies an incoming support ticket into category and priority.",
      "prompt_type": "system",
      "target_model": "claude-sonnet-4-6",
      "intent": "Triage user support tickets...",
      "current_version": 12,
      "created_at": "2026-04-01T18:31:00.000Z",
      "updated_at": "2026-04-23T09:14:25.000Z"
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 1 }
}

Response shape (PromptSummary[]).

Summaries don't include content

List endpoints return summaries only · no current_content, no tags, no folder_id. To read content, fetch a single prompt or its resolved twin.

Get one prompt

Returns the full Prompt row including content, folder reference, tags, and metadata.

curl -H "Authorization: Bearer pa_live_..." \
  https://promptassay.ai/api/v1/prompts/0a1b2c3d-1e2f-...

{
  "data": {
    "id": "0a1b2c3d-...",
    "title": "Support triage classifier",
    "description": "...",
    "current_content": "<role>You are a support triage assistant...</role>...",
    "prompt_type": "system",
    "target_model": "claude-sonnet-4-6",
    "intent": "...",
    "current_version": 12,
    "folder_id": "8b7a6c5d-...",
    "is_favorite": false,
    "is_archived": false,
    "sort_order": 100,
    "tags": [
      { "id": "11111111-...", "name": "production", "color": "#cc6644" }
    ],
    "created_at": "2026-04-01T18:31:00.000Z",
    "updated_at": "2026-04-23T09:14:25.000Z"
  }
}

Response shape (Prompt).

Get resolved content

Returns the prompt with every fragment reference inlined and {{var}} slots substituted. This is the call you make at runtime when shipping a prompt to your LLM provider · the resolved_content field is ready to send.

How resolution actually works

Resolution starts from prompt.current_content. Each row in the prompt_fragments join table (ordered by position) appends \n\n + the fragment's content with its {{var}} slots replaced from the join row's variable_overrides map. Take no query params · all variable bindings come from the join row, set when you composed the prompt in the editor. See Composing prompts from fragments.

curl -H "Authorization: Bearer pa_live_..." \
  https://promptassay.ai/api/v1/prompts/0a1b2c3d-.../resolved

{
  "data": {
    "id": "0a1b2c3d-...",
    "title": "Support triage classifier",
    "prompt_type": "system",
    "target_model": "claude-sonnet-4-6",
    "resolved_content": "<role>...</role>\n\n<style>...</style>",
    "fragment_count": 2
  }
}

Response shape (ResolvedPrompt).

List versions

Returns a paginated list of version summaries for a prompt, ordered by version_number DESC. Wrong-tenant or missing prompt returns 404.

curl -H "Authorization: Bearer pa_live_..." \
  "https://promptassay.ai/api/v1/prompts/{id}/versions?per_page=20"

{
  "data": [
    {
      "version_number": 12,
      "change_summary": "Applied 2 Improve suggestions",
      "change_source": "ai-improve",
      "created_at": "2026-04-23T09:14:25.000Z"
    },
    {
      "version_number": 11,
      "change_summary": "Tightened the role definition",
      "change_source": "manual",
      "created_at": "2026-04-22T14:01:08.000Z"
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 12 }
}

Response shape (VersionSummary[]).

Free-tier 7-day cutoff

On Free tier the listing is filtered to versions created in the last 7 days. Older versions stay in the database and reappear on upgrade. Solo and Team see the full history.

Get one version

Returns a single version row with full content. The version path param is a positive integer (the version_number from the listing). Wrong-prompt OR wrong-version both return 404 with Version not found.

curl -H "Authorization: Bearer pa_live_..." \
  https://promptassay.ai/api/v1/prompts/{id}/versions/12

{
  "data": {
    "id": "9c8b7a6d-...",
    "prompt_id": "0a1b2c3d-...",
    "version_number": 12,
    "content": "<role>...</role>...",
    "change_summary": "Applied 2 Improve suggestions",
    "change_source": "ai-improve",
    "parent_version_id": "ab12cd34-...",
    "metadata": { /* e.g. { applied_suggestions: 2 } */ },
    "created_at": "2026-04-23T09:14:25.000Z"
  }
}

Response shape (Version).

Limits

Pagination: per_page default 20, max 100.
Rate limit: 100 req/min per key, 500 req/min global.
Tier gate: Solo or higher; Free returns 403 API_NOT_ALLOWED.
Free-tier version cutoff: 7 days on /versions and /versions/{n}.
Method support: GET only; mutations not exposed in this release.

Read-only API

Every endpoint listed here is a GET. There's no POST /prompts, no PATCH /prompts/{id}, no POST /prompts/{id}/run. Mutations and runtime LLM calls are workbench-only in this release. Tell us what shape you'd want · the roadmap is open.

← All docs Open the workbench →