Prompt Aliases API

All endpoints accept either a session cookie (connect.sid) or a Bearer API key. Promote requires owner, admin, or editor role. Render and list are read-only (any authenticated user).

GET /api/v1/prompts/:id/aliases

Lists all aliases for a prompt, including which version each alias points to.

curl $ACRUXCORE_BASE_URL/prompts/a95ea910-c7fc-43c5-9c68-a8750e02a8f5/aliases \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY"

Response (status 200):

[
  {
    "id": "dfa7b5d8-b13d-4c2f-9f4f-055677cab1e1",
    "alias": "production",
    "versionId": "1f720cc8-c817-45a1-a992-02dd2f90af64",
    "versionNumber": 1,
    "updatedAt": "2026-06-26T22:39:53.859Z"
  },
  {
    "id": "f1112da8-dcd5-4f8b-a633-2fc0373157ea",
    "alias": "staging",
    "versionId": "1f720cc8-c817-45a1-a992-02dd2f90af64",
    "versionNumber": 1,
    "updatedAt": "2026-06-26T22:39:53.859Z"
  }
]

POST /api/v1/prompts/:id/aliases/:alias/promote

Promotes (or creates) an alias to point to a specific version number. Also used to roll back by promoting to an earlier version number. The alias can be any string (production, staging, canary, etc.).

Promote production to v2:

curl
TypeScript
Python

curl -X POST $ACRUXCORE_BASE_URL/prompts/a95ea910-c7fc-43c5-9c68-a8750e02a8f5/aliases/production/promote \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version_number":2}'

const alias = await hub.prompts.promoteAlias('a95ea910-c7fc-43c5-9c68-a8750e02a8f5', 'production', 2);

alias = await hub.prompts.promote_alias('a95ea910-c7fc-43c5-9c68-a8750e02a8f5', 'production', 2)

Response (status 200):

{
  "id": "dfa7b5d8-b13d-4c2f-9f4f-055677cab1e1",
  "alias": "production",
  "versionId": "e3d0901f-24e6-4ada-941e-5b590592d2f8",
  "versionNumber": 2,
  "updatedAt": "2026-06-26T22:42:29.884Z"
}

Rollback production to v1:

curl -X POST $ACRUXCORE_BASE_URL/prompts/a95ea910-c7fc-43c5-9c68-a8750e02a8f5/aliases/production/promote \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version_number":1}'

Response (status 200):

{
  "id": "dfa7b5d8-b13d-4c2f-9f4f-055677cab1e1",
  "alias": "production",
  "versionId": "1f720cc8-c817-45a1-a992-02dd2f90af64",
  "versionNumber": 1,
  "updatedAt": "2026-06-26T22:42:29.915Z"
}

400 — version_number missing from body:

{"error":{"code":"VALIDATION_ERROR","message":"..."}}

403 — viewer role cannot promote:

{"error":{"code":"FORBIDDEN","message":"You do not have permission to perform this action."}}

404 — version number does not exist for this prompt:

{"error":{"code":"NOT_FOUND","message":"Version 99 not found for this prompt"}}

POST /api/v1/prompts/:name/:alias/render

Renders a prompt by its name (slug) and alias, substituting Jinja2/nunjucks variables. The alias resolves to whatever version is currently promoted.

Render production (v1) — requires name + company variables:

curl -X POST $ACRUXCORE_BASE_URL/prompts/greeting/production/render \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"name":"Alice","company":"Acme Corp"}}'

Response (status 200) — v1 content rendered:

{
  "messages": [
    {
      "role": "system",
      "content": "Hello Alice, welcome to Acme Corp."
    }
  ],
  "tools": [],
  "toolResolutions": [],
  "model": null,
  "versionId": "475725df-725a-45c6-a195-05ca2e29cb95",
  "versionNumber": 1
}

versionId/versionNumber identify the exact prompt version that produced this render — pass either through as promptVersionId on the SDK's chat()/runToolLoop() so a trace can be linked back to it.

A version with an image part renders the image url the same way as text. Rendering the version from Add an image to a message:

curl -X POST $ACRUXCORE_BASE_URL/prompts/receipt-reader-573/production/render \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"kind":"receipt","receipt_url":"https://example.com/receipts/blue-heron.png"}}'

# Response (status 200)
{"messages":[{"role":"system","content":"You read receipts. Reply with the merchant name and the total only."},{"role":"user","content":[{"type":"text","text":"Read this receipt."},{"type":"image_url","image_url":{"url":"https://example.com/receipts/blue-heron.png"}}]}],"tools":[],"toolResolutions":[],"model":null,"versionId":"b660dbf5-ae38-4b22-8d4e-386def5a8c76","versionNumber":1}

The variable that fills the image is required like any other:

curl -X POST $ACRUXCORE_BASE_URL/prompts/receipt-reader-573/production/render \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"kind":"receipt"}}'

# Response (status 400)
{"error":{"code":"MISSING_VARIABLES","message":"Required variables are missing: receipt_url","missing":["receipt_url"]}}

tools (TC3) is always present — an array of OpenAI-shaped function definitions for the Tool Catalog tools bound to the alias being rendered, or [] when it has none. toolResolutions is a parallel array — one entry per tools entry, same order — reporting which tool alias (or pin) each one actually resolved through, its version number, and whether the binding that decided it belonged to this prompt alias (source: "alias") or was inherited from the prompt's default (source: "default"). Curl-verified against an alias inheriting the default binding:

curl -X POST $ACRUXCORE_BASE_URL/prompts/weather-brief/production/render \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"city":"Lisbon"}}'

Response (status 200):

{
  "messages": [
    { "role": "user", "content": "What is the weather in Lisbon?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather conditions for a city.",
        "parameters": {
          "type": "object",
          "required": ["city"],
          "properties": { "city": { "type": "string", "description": "City name, e.g. Lahore." } }
        }
      }
    }
  ],
  "toolResolutions": [
    { "name": "get_weather", "alias": "production", "versionNumber": 3, "source": "default" }
  ],
  "model": null,
  "versionId": "512f8ed0-caf7-46d9-8287-712926f8f606",
  "versionNumber": 2
}

Rendering the same prompt through staging, which has its own binding pointing get_weather at the tool's staging alias:

curl -X POST $ACRUXCORE_BASE_URL/prompts/weather-brief/staging/render \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"city":"Lisbon"}}'

Response (status 200) — same tool, an older build of it, and source now names the alias rather than the default:

{
  "messages": [
    { "role": "user", "content": "What's the weather in Lisbon right now? Answer in one short sentence." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
          "type": "object",
          "required": ["city"],
          "properties": { "city": { "type": "string", "description": "City name, e.g. Lahore." } }
        }
      }
    }
  ],
  "toolResolutions": [
    { "name": "get_weather", "alias": "staging", "versionNumber": 1, "source": "alias" }
  ],
  "model": null,
  "versionId": "f20d87d8-3000-445b-9fea-ae3f59cacb9c",
  "versionNumber": 1
}

After promoting production to v2:

curl -X POST $ACRUXCORE_BASE_URL/prompts/greeting/production/render \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"name":"Alice","company":"Acme Corp"}}'

Response (status 200) — v2 content rendered:

{
  "messages": [
    {
      "role": "system",
      "content": "Hi there Alice, Acme Corp is glad you are here."
    }
  ],
  "tools": [],
  "toolResolutions": [],
  "model": null,
  "versionId": "b10ae99f-ff5d-4df6-a0d4-f33740ef950f",
  "versionNumber": 2
}

400 MISSING_VARIABLES — required template variables absent:

{
  "error": {
    "code": "MISSING_VARIABLES",
    "message": "Required variables are missing: company, name",
    "missing": ["company", "name"]
  }
}

404 — prompt name not found:

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

404 — alias not found for this prompt:

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

Render a pinned version

Add version to the body to render that version number instead of the one the alias points at. The alias still decides which tools come back, and no alias moves. The SDKs send this field while a run pins the prompt with prompt_overrides / promptOverrides. The production alias of brewline-support points at v2 here:

curl -X POST $ACRUXCORE_BASE_URL/prompts/brewline-support/production/render \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"question":"Is my grinder broken?","today":"2026-10-26"},"version":3}'

Response (status 200):

{
  "messages": [
    {
      "role": "system",
      "content": "You are Brewline's friendly customer support assistant. Today's date is 2026-10-26.\n\nBefore each response, consult Brewline's official policies and use the policy search and order lookup tools for precise, up-to-date information. Provide answers in two to four sentences, clearly stating the Brewline policy that applies and how it affects this customer's order or question. Give specific next steps the customer should follow based on their situation. Do not give general or unofficial advice."
    },
    { "role": "user", "content": "Is my grinder broken?" }
  ],
  "tools": [],
  "toolResolutions": [],
  "model": "gpt-4o-mini",
  "versionId": "1205ece2-44de-4b01-b401-d5a6ccf76fb3",
  "versionNumber": 3
}

404 — the prompt has no such version:

curl -X POST $ACRUXCORE_BASE_URL/prompts/brewline-support/production/render \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"question":"x","today":"2026-10-26"},"version":99}'

{"error":{"code":"NOT_FOUND","message":"Version 99 not found for prompt \"brewline-support\""}}

GET /api/v1/prompt-versions?name=&alias=

Returns the version an alias points at, found by the prompt's name, with its template unrendered: messages keep their {{ placeholders }}. Use it when your app renders templates itself. Use render when the server should fill them in. The body has the same shape as GET /prompts/:id/versions/:n. name is required and must match exactly. Send alias, or version for one exact version number. With both, the alias must still exist, as it must on a pinned render, and the version comes from version. Any role can call it, with a session or an API key.

curl "$ACRUXCORE_BASE_URL/prompt-versions?name=e2e-review2-triage&alias=production" \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY"

Response (status 200):

{
  "id": "79bdae37-3b84-4980-bac7-b1455886e0b4",
  "promptId": "9fa9726d-1d42-4bb5-8230-d7c5e6764089",
  "versionNumber": 1,
  "messages": [
    {
      "role": "system",
      "content": "Triage {{ ticket }}"
    }
  ],
  "variables": [
    "ticket"
  ],
  "createdBy": "18c76b52-ee0d-4001-be8e-c29976488fbb",
  "createdAt": "2026-10-16T20:51:49.093Z",
  "model": null
}

404 — no prompt of that name in your team, or the prompt has no such alias:

curl "$ACRUXCORE_BASE_URL/prompt-versions?name=e2e-review2-triage&alias=canary" \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY"

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

400 — a parameter is missing:

curl "$ACRUXCORE_BASE_URL/prompt-versions?name=e2e-review2-triage" \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY"

{"error":{"code":"VALIDATION_ERROR","message":"alias or version is required"}}

By version number instead of alias:

curl "$ACRUXCORE_BASE_URL/prompt-versions?name=brewline-support&version=3" \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY"

Response (status 200):

{
  "id": "1205ece2-44de-4b01-b401-d5a6ccf76fb3",
  "promptId": "086e7d40-c76d-44f4-b395-d82a24919941",
  "versionNumber": 3,
  "messages": [
    {
      "role": "system",
      "content": "You are Brewline's friendly customer support assistant. Today's date is {{ today }}.\n\nBefore each response, consult Brewline's official policies and use the policy search and order lookup tools for precise, up-to-date information. Provide answers in two to four sentences, clearly stating the Brewline policy that applies and how it affects this customer's order or question. Give specific next steps the customer should follow based on their situation. Do not give general or unofficial advice."
    },
    { "role": "user", "content": "{{ question }}" }
  ],
  "variables": ["question", "today"],
  "createdBy": "73f122c0-9260-4384-b0da-9b20d56e18c8",
  "createdAt": "2026-10-25T20:57:00.492Z",
  "model": "gpt-4o-mini"
}

With a pin, a misspelled alias is refused, as it is on render:

curl "$ACRUXCORE_BASE_URL/prompt-versions?name=brewline-support&alias=prodution&version=3" \
  -H "Authorization: Bearer $ACRUXCORE_API_KEY"

Response (status 404):

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

GET /api/v1/prompts/:id/aliases​

POST /api/v1/prompts/:id/aliases/:alias/promote​

POST /api/v1/prompts/:name/:alias/render​

Render a pinned version​

GET /api/v1/prompt-versions?name=&alias=​

GET /api/v1/prompts/:id/aliases

POST /api/v1/prompts/:id/aliases/:alias/promote

POST /api/v1/prompts/:name/:alias/render

Render a pinned version

GET /api/v1/prompt-versions?name=&alias=