How to send queries to your AI circuits and retrieve their results using the ModelWorks API.

Querying AI Circuits

Once you’ve created and published a circuit, you can invoke it via the ModelWorks API. This guide covers authentication, request format, polling vs. push, and retrieving both in-flight and completed results for the POST /circuit-adaptors/{adaptor_uid}/query endpoint.

Base URL

All examples assume the following base URL:

Text

https://modelworks.ai/api

Authentication

All requests must include a valid bearer token in the Authorization header. Tokens can be managed under your user settings (API Tokens section).

Text

Authorization: Bearer <YOUR_API_TOKEN>
Content-Type: application/json

Submitting a Query

POST /circuit-adaptors/{adaptor_uid}/query

Send a JSON payload describing which circuit version to run and your input parameters.

Request

URL: /circuit-adaptors/{adaptor_uid}/query
Method: POST
Headers:
- Authorization: Bearer token
- Content-Type: application/json

Body Schema

JSON

{
  "context": {
    "version": "<circuit_version_uuid>"
  },
  "input": {
    "<input_field_name>": <value>,
    ...
  },
  // optional: only circuit owner may set
  "is_public": false
}

Field	Type	Description
`context.version`	string	UUID of the specific circuit version to invoke.
`input`	object	Key/value pairs matching the circuit’s query schema.
`is_public` (opt.)	boolean	Mark run public (only circuit owner may set). Default is `false`.

Example

Bash

curl -X POST https://modelworks.ai/api/circuit-adaptors/{adaptor_uid}/query \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "context": { "version": "73120d53-bf89-44fa-a035-5b88fe41574a" },
    "input": {
      "fetch_url": "https://api.ipify.org?format=json"
    }
  }'

Immediate Response

Returns HTTP 200 OK with a minimal CircuitRun stub:

JSON

{
  "status": "success",
  "payload": {
    "uid": "fdd8a9c2-695a-4ef3-95c6-0be1cba77cc6",
    "state": "PROVISIONED",
    "is_public": false
  }
}

The run begins in state PROVISIONED → RUNNING asynchronously. You can poll or subscribe (SSE) on updates.

Retrieving Run Results

Once a run reaches a terminal state, you can fetch its full details.

GET /circuit-runs/{uid}

URL: /circuit-runs/{uid}
Method: GET
Headers:
- Authorization: Bearer <YOUR_API_TOKEN> (required if is_public=false)

Note: Runs marked is_public=true are viewable by anyone; private runs require the owner’s token.

Path Parameters

Name	Type	Description
`uid`	string	UUID of the `CircuitRun` to retrieve.

Example

Bash

curl https://modelworks.ai/api/circuit-runs/fdd8a9c2-695a-4ef3-95c6-0be1cba77cc6 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Successful Response

JSON

{
  "status": "success",
  "payload": {
    "uid": "fdd8a9c2-695a-4ef3-95c6-0be1cba77cc6",
    "user_uid": "4a1b2c3d-...",
    "circuit_uid": "73120d53-...",
    "circuit_version_uid": "73120d53-...",
    "created_at": "2025-06-23T18:25:43.511Z",
    "ended_at": "2025-06-23T18:25:45.122Z",
    "state": "COMPLETED",
    "is_public": false,
    "document_type": "circuit_run",
    "result_blob": {
      // full JSON of step-by-step outputs
    }
  }
}

`CircuitRun` Fields

Field	Type	Description
`uid`	string	Unique run identifier.
`state`	string	One of `PROVISIONED`, `RUNNING`, `COMPLETED`, `EXCEPTION`, etc.
`result_blob`	object	Full JSON output from the circuit’s steps (present when completed).
`created_at` / `ended_at`	string (ISO 8601)	Timestamps for run start and finish.
`is_public`	boolean	Whether this run is publicly viewable.
…	…	(Other metadata fields as shown above.)

Error Responses

HTTP Status	Code	Description
400 Bad Request	`BadClientData`	Invalid payload or failed schema validation
401 Unauthorized	`Unauthorized`	Missing or invalid bearer token
403 Forbidden	`NotAllowed`	Insufficient permission to view or run
404 Not Found	`NotFound`	Circuit version or run UUID does not exist

Example: Unauthorized

HTTP

HTTP/1.1 401 Unauthorized
{
  "error": {
    "message": "Must be logged in to view this private run",
    "code": "Unauthorized"
  }
}

Best Practices

Poll sparingly: Use exponential back-off or switch to SSE for live updates.
Cache your primary version: Fetch it once via GET /circuits/{circuit_uid}/primary and reuse.
Monitor credits: Each run consumes credits—track usage in the dashboard.

Bash

# Fetch primary version UUID
curl https://modelworks.ai/api/circuits/73120d53-.../primary \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Querying AI Circuits

On this page