Circuit Versions

A circuit version is a specific, immutable snapshot of your circuit's definition (circuit.json). Every time you change your circuit, you create a new version. This guide covers creating, validating, fetching, and annotating versions. For the parent circuit, see Managing Circuits.

Base URL

All examples assume the following base URL:

https://modelworks.ai/api

Authentication

All endpoints below require an API token sent as Authorization: Bearer YOUR_API_TOKEN. See Authentication. List endpoints support limit and page pagination and return a meta object with total_count, limit, and page.

Create a version

POST /users/{username}/circuits/{circuit_name}/circuit-versions

Create a new version under your circuit. Owner only. The request body contains the circuit definition JSON.

Path parameters

Example

curl -X POST https://modelworks.ai/api/users/modelworks/circuits/SEC-Filing-Discovery/circuit-versions \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @circuit.json

After creation, the version enters STAGING and moves to VALIDATING, then VALIDATED once checks pass.

Validate a version

POST /circuit-versions/validate

Validate a circuit definition before creating a version. Upload your circuit.json as a multipart file. Returns validation results without persisting anything — a great way to catch schema errors during CI.

curl -X POST https://modelworks.ai/api/circuit-versions/validate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@circuit.json"

Get a version

GET /circuit-versions/{uid}

Fetch a single version by its UID. Whether the source code and full schema are included depends on the circuit's visibility and whether you're the owner: public circuits expose their definition to everyone; private/protected circuits expose it only to the owner.

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

Update a version's README

PUT /circuit-versions/{uid}/readme

Update the README markdown attached to a version. Owner only.

curl -X PUT https://modelworks.ai/api/circuit-versions/8c5db2d9-d8a5-4752-a7a2-b31ae763d988/readme \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: text/plain" \
  -d @README.md

Update a version's license

PUT /circuit-versions/{uid}/license

Update the LICENSE file attached to a version. Owner only.

curl -X PUT https://modelworks.ai/api/circuit-versions/8c5db2d9-d8a5-4752-a7a2-b31ae763d988/license \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: text/plain" \
  -d @LICENSE.md

Version states

Each version moves through a lifecycle. The common states are:

Get pricing

GET /circuit-versions/{uid}/circuit-pricing

Returns the pricing information for a version. Private circuits require ownership; public/protected circuits expose pricing to anyone.

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

List runs for a version

GET /circuit-versions/{version_uid}/circuit-runs

List the completed public runs for a version. Paginated.

curl "https://modelworks.ai/api/circuit-versions/8c5db2d9-d8a5-4752-a7a2-b31ae763d988/circuit-runs?limit=10&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Tip: Only completed public runs are listed here. For private runs and full details, see Circuit Runs.