Circuit Prompts

Prompts are reusable template text snippets that a circuit version can reference. Inside your circuit definition you interpolate a prompt by name — for example, `${{ prompts.system_instructions }}` — and at runtime ModelWorks substitutes the prompt's content. Keeping prompts separate from your circuit JSON makes them easy to edit, version, and reuse across steps.

All prompt endpoints are scoped to a circuit version UID and require an API token (Authorization: Bearer YOUR_API_TOKEN). See Authentication.

Base URL

All examples assume the following base URL:

https://modelworks.ai/api

List prompts

GET /circuit-versions/{uid}/prompts

List every prompt attached to a version. Public versions are readable by anyone; private/protected versions require read access.

curl https://modelworks.ai/api/circuit-versions/8c5db2d9-d8a5-4752-a7a2-b31ae763d988/prompts \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get a prompt

GET /circuit-versions/{uid}/prompts/{name}

Fetch a single prompt by its name.

curl https://modelworks.ai/api/circuit-versions/8c5db2d9-d8a5-4752-a7a2-b31ae763d988/prompts/system_instructions \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Create a prompt

POST /circuit-versions/{uid}/prompts

Create a new prompt. Owner only.

Request body

Example

curl -X POST https://modelworks.ai/api/circuit-versions/8c5db2d9-d8a5-4752-a7a2-b31ae763d988/prompts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "system_instructions",
    "content": "You are a helpful SEC filings analyst."
  }'

Update a prompt

PUT /circuit-versions/{uid}/prompts/{name}

Update an existing prompt's content. Owner only.

curl -X PUT https://modelworks.ai/api/circuit-versions/8c5db2d9-d8a5-4752-a7a2-b31ae763d988/prompts/system_instructions \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "You are a meticulous SEC filings analyst. Cite sources."
  }'

Delete a prompt

DELETE /circuit-versions/{uid}/prompts/{name}

Permanently delete a prompt. Owner only. Deleting a prompt that your circuit still references will cause runs to fail, so check requirements first.

curl -X DELETE https://modelworks.ai/api/circuit-versions/8c5db2d9-d8a5-4752-a7a2-b31ae763d988/prompts/system_instructions \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Check prompt requirements

GET /circuit-versions/{uid}/prompts/check

ModelWorks inspects your circuit definition for every prompt it references and reports which are satisfied (a prompt with that name exists) and which are missing. Run this before activating a new version to avoid runtime failures.

curl https://modelworks.ai/api/circuit-versions/8c5db2d9-d8a5-4752-a7a2-b31ae763d988/prompts/check \
  -H "Authorization: Bearer YOUR_API_TOKEN"

The response typically lists satisfied and missing prompt names so you can fix gaps before going live.