---
title: "Call a workspace prompt"
method: POST
path: "/v1/prompts/{promptId}/completions"
---

# Call a workspace prompt

`POST /v1/prompts/{promptId}/completions`

## Request

- Base URL: `https://api.agentlab.cresclab.com`
- URL: `https://api.agentlab.cresclab.com/v1/prompts/{promptId}/completions`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/cresclab/apis/agent-lab-ai-gateway/docs/v1/prompts/:promptId/completions/post.ts> (a function with typed inputs; its response is checked against the schema)

Portkey-style prompt call. The path names a prompt from the workspace's prompt library by id or slug; append @<version> to pin a version, otherwise the published version answers. The body carries variables, which must be exactly the prompt's, and any Chat Completions member except messages, which overrides what the prompt sets. Answered exactly as /v1/chat/completions, through the same key, limits, auto routing and usage; the request records the prompt and version.

## Path parameters

- `promptId` string, required

## Headers

- `X-AgentLab-Routing` 'auto' | 'auto:cost' | 'auto:balanced' | 'auto:quality'
- `Idempotency-Key` string

## Request body

- PromptCompletionRequest
  - `variables` object: One string for each {{variable}} the prompt uses; a missing or extra one is refused with prompt_variables_mismatch.
  - `model` string: Overrides the prompt's model: auto or a name from GET /v1/models.
  - `stream` boolean
  - `user` string: Recorded as the request's end user.

## Response `200`

The model's answer, or a text/event-stream when stream is true.

- object

## Other responses

- `400`: Refused request. See the error catalog.
- `401`: Missing or not accepted key.
- `403`: Not allowed for this key or workspace.
- `404`: The key's workspace has no prompt, or no such version, by that name (prompt_not_found).
- `429`: Rate limited or out of allowance. Retry-After and X-Should-Retry say whether to retry.
- `502`: The provider failed to answer.
- `503`: Gateway unavailable or settlement pending.

---

[API](https://skmtc.dev/cresclab/apis/agent-lab-ai-gateway.md) - [All operations](https://skmtc.dev/cresclab/apis/agent-lab-ai-gateway/llms.txt) - [OpenAPI document](https://skmtc.dev/cresclab/apis/agent-lab-ai-gateway/revisions/5dc08011cbe9?raw)