Managing Circuits

A circuit is your versioned, reusable unit of AI logic on ModelWorks. This guide covers everything you can do with a circuit itself — creating one, fetching it, updating its metadata, starring it, and deprecating it. For the versions inside a circuit, see Circuit Versions.

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, unless the endpoint is marked public. See Authentication.

All list endpoints support pagination with limit (items per page) and page (1-based page number), and return a meta object containing total_count, limit, and page.

Create a circuit

POST /circuits

Creates a new circuit owned by the authenticated user.

Request body

Example

curl -X POST https://modelworks.ai/api/circuits \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SEC Filing Discovery",
    "description": "Finds SEC filings for a given ticker.",
    "is_private": false,
    "is_protected": false,
    "license_type": "mit"
  }'

Response (200 OK)

Returns the created circuit object, including its uid, name, description, visibility flags, and timestamps.

Get a circuit

You can fetch a circuit three ways: by its UID, by owner + name, or just its primary version UID.

GET /circuits/{circuit_uid}

Fetch a circuit by its unique ID. Public circuits need no auth; private or protected circuits require the owner's token.

curl https://modelworks.ai/api/circuits/73120d53-bf89-44fa-a035-5b88fe41574a \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET /users/{username}/circuits/{circuit_name}

Fetch a circuit by its owner's username and the circuit's name. This is handy when you only know the human-readable names (for example, modelworks/SEC-Filing-Discovery).

curl https://modelworks.ai/api/users/modelworks/circuits/SEC-Filing-Discovery \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET /circuits/{circuit_uid}/primary

Returns the UID of the circuit's primary version — the version that gets run when callers don't pin a specific one. Cache this and reuse it instead of re-fetching on every request.

curl https://modelworks.ai/api/circuits/73120d53-bf89-44fa-a035-5b88fe41574a/primary \
  -H "Authorization: Bearer YOUR_API_TOKEN"

List circuits

GET /users/{username}/circuits

List a user's public circuits. No authentication is needed to view public circuits; include your token only if you want to see private ones you own.

curl "https://modelworks.ai/api/users/modelworks/circuits?limit=20&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET /circuits/{circuit_uid}/circuit-versions

List the versions of a circuit, newest first. Pagination applies.

curl "https://modelworks.ai/api/circuits/73120d53-bf89-44fa-a035-5b88fe41574a/circuit-versions?limit=10&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Update a circuit

PUT /users/{username}/circuits/{circuit_name}

Update a circuit's metadata or visibility. Owner only.

Request body

All fields are optional — send only the ones you want to change.

Example

curl -X PUT https://modelworks.ai/api/users/modelworks/circuits/SEC-Filing-Discovery \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Finds SEC filings for a given ticker (updated).",
    "is_private": true
  }'

Deprecate a circuit

PUT /circuits/{circuit_uid}/deprecate

Marks the circuit and all of its versions as deprecated. Owner only. Deprecated circuits still run, but callers see deprecation notices.

curl -X PUT https://modelworks.ai/api/circuits/73120d53-bf89-44fa-a035-5b88fe41574a/deprecate \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Star and unstar

Starring is a way to bookmark circuits you find useful.

POST /users/{username}/circuits/{circuit_name}/stars

Star a circuit. Requires an API token.

curl -X POST https://modelworks.ai/api/users/modelworks/circuits/SEC-Filing-Discovery/stars \
  -H "Authorization: Bearer YOUR_API_TOKEN"

DELETE /users/{username}/circuits/{circuit_name}/stars

Unstar a circuit.

curl -X DELETE https://modelworks.ai/api/users/modelworks/circuits/SEC-Filing-Discovery/stars \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET /users/{username}/circuits/{circuit_name}/stars

Check whether you have starred a circuit. Returns a boolean.

curl https://modelworks.ai/api/users/modelworks/circuits/SEC-Filing-Discovery/stars \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET /users/stars

List the circuits you have starred (up to 50).

curl https://modelworks.ai/api/users/stars \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Check access

GET /users/{username}/circuits/{circuit_name}/ping

Returns a boolean indicating whether you can read the circuit. No auth required. This is a cheap way to check access before attempting a heavier query call.

curl https://modelworks.ai/api/users/modelworks/circuits/SEC-Filing-Discovery/ping

Embeds

GET /users/{username}/circuits/{circuit_name}/embeds

List the circuits that embed this one. Paginated, max 200 results.

curl "https://modelworks.ai/api/users/modelworks/circuits/SEC-Filing-Discovery/embeds?limit=20&page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Explain

GET /users/{username}/circuits/{circuit_name}/explain

Returns the circuit's explain detail — a human-readable breakdown of what the circuit does. Visibility is gated by the circuit's visibility settings and your access.

curl https://modelworks.ai/api/users/modelworks/circuits/SEC-Filing-Discovery/explain \
  -H "Authorization: Bearer YOUR_API_TOKEN"