Skip to main content

Prompts API

All endpoints verified working via curl. Document updated only after curl confirmation.

:::note Create, edit, and delete happen in the dashboard POST, PATCH, and DELETE below only accept a dashboard session today — a Bearer API key gets 401 UNAUTHORIZED on them. Author prompts in Prompts → New prompt in the web app; use the API (with a Bearer token) to read, search, and resolve them from your code. See Authentication for how to generate a token. :::

POST /api/v1/prompts​

Creates a new prompt. Dashboard session only (see note above). Role must be owner, admin, or editor (viewer returns 403).

Response (status 201):

{
  "id": "5fd454e0-bdb2-4468-b369-7fbb3f252dca",
  "name": "customer-support",
  "description": "Handles customer support queries",
  "teamId": "a1ab6500-4819-44cf-bb42-14e637cbb51d",
  "createdBy": "94925fcd-3caa-4969-a293-25304121c77b",
  "createdAt": "2026-06-26T22:12:17.574Z"
}

Missing name (status 400):

{ "error": { "code": "VALIDATION_ERROR", "message": "name is required." } }

Viewer role (status 403):

{ "error": { "code": "FORBIDDEN", "message": "Insufficient role for this action." } }

GET /api/v1/prompts​

Lists active (non-deleted) prompts for the current team. Supports ?search=, ?page=, ?limit=.

curl -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  "$ACRUXCORE_BASE_URL/prompts"

Or with search:

curl -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  "$ACRUXCORE_BASE_URL/prompts?search=customer"

Response (status 200):

{
  "data": [
    {
      "id": "5fd454e0-bdb2-4468-b369-7fbb3f252dca",
      "name": "customer-support",
      "description": "Handles customer support queries",
      "createdAt": "2026-06-26T22:12:17.574Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

GET /api/v1/prompts/:id​

curl -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  "$ACRUXCORE_BASE_URL/prompts/5fd454e0-bdb2-4468-b369-7fbb3f252dca"

Response (status 200):

{
  "id": "5fd454e0-bdb2-4468-b369-7fbb3f252dca",
  "name": "customer-support",
  "description": "Handles customer support queries",
  "teamId": "a1ab6500-4819-44cf-bb42-14e637cbb51d",
  "createdBy": "94925fcd-3caa-4969-a293-25304121c77b",
  "createdAt": "2026-06-26T22:12:17.574Z"
}

Unknown id, soft-deleted, or belongs to another team (status 404):

{ "error": { "code": "NOT_FOUND", "message": "Prompt not found." } }

PATCH /api/v1/prompts/:id​

Partially updates name and/or description. Dashboard session only (see note above). At least one field required. Role must be owner, admin, or editor.

Response (status 200) — returns the updated prompt:

{
  "id": "5fd454e0-bdb2-4468-b369-7fbb3f252dca",
  "name": "customer-support-v2",
  "description": "Handles customer support queries",
  "teamId": "a1ab6500-4819-44cf-bb42-14e637cbb51d",
  "createdBy": "94925fcd-3caa-4969-a293-25304121c77b",
  "createdAt": "2026-06-26T22:12:17.574Z"
}

Empty body (status 400):

{ "error": { "code": "VALIDATION_ERROR", "message": "At least one of name or description must be provided." } }

DELETE /api/v1/prompts/:id​

Soft-deletes the prompt (sets deleted_at). History is preserved. Dashboard session only (see note above). Role must be owner, admin, or editor.

Response (status 204) — no body. Prompt disappears from GET /prompts and GET /prompts/:id.

Already deleted or not found (status 404):

{ "error": { "code": "NOT_FOUND", "message": "Prompt not found." } }

GET /api/v1/prompt-versions/:versionId​

Resolves a prompt-version UUID to its parent prompt + raw template messages. Used to prefill the Playground from a trace/feedback span (which carries only the version UUID). Any authenticated role. Team-scoped: a version belonging to another team returns 404 (no cross-team leak). model (issue #12) is the version's bound default model publicName, or null if unbound/deleted.

curl -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  "$ACRUXCORE_BASE_URL/prompt-versions/cc79f29c-d4bf-4ea0-a162-ae59f9366bd7"

Response (status 200):

{
  "promptId": "9aa612d3-adca-4636-be06-f62465af63e6",
  "promptName": "greeting",
  "versionNumber": 1,
  "messages": [
    { "role": "system", "content": "You are helpful." },
    { "role": "user", "content": "Greet {{ name }}." }
  ],
  "variables": ["name"],
  "tools": [],
  "model": "gpt-4o-mini"
}

Not found or cross-team (status 404):

{ "error": { "code": "NOT_FOUND", "message": "Prompt version not found" } }