Querying Circuit Adaptors

ModelWorks circuits can expose one or more adaptors—pre‑configured integrations (e.g. OpenAI, ModelWorks SSE)—that let you send requests through different back‑ends or protocols. Each adaptor has a unique uid and an adapter_type, and supports a streaming (SSE) query interface.

Querying an Adaptor

curl -N https://modelworks.ai/api/circuit-adaptors/{adaptor_uid}/query \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request.json

• -N enables HTTP server‑sent events (SSE) streaming.
• Replace {adaptor_uid} with the adaptor's UID as shown on the circuit's Adaptors tab.
• Supply your Bearer token to authenticate.
• The JSON payload format varies by adaptor type.

ModelWorks SSE Adaptor

For adaptors of type ModelworksSse, the request schema is defined in the circuit’s JSON definition. You must include a top‑level context.version field and an input object matching that schema. Example request.json:

{
  "context": { "version": "8c5db2d9-d8a5-4752-a7a2-b31ae763d988" },
  "input": {
    "messages": [
      { "role": "system",  "content": "You are a helpful assistant." },
      { "role": "user",    "content": "What LLMs give realtime information?" }
    ]
  }
}

curl -N https://modelworks.ai/api/circuit-adaptors/ab6ecbc7-ecdb-4b6e-9c81-184b3282a6e1/query \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @request.json

OpenAI SSE Adaptor

Adaptors of type OpenAiSse follow the OpenAI API’s chat format. Include model, messages, and stream: true directly:

{
  "model": "gpt-4o-mini",
  "messages": [
    { "role": "system",  "content": "You are a helpful assistant." },
    { "role": "user",    "content": "What LLMs give realtime information?" }
  ],
  "stream": true
}

curl -N https://modelworks.ai/api/circuit-adaptors/ab6ecbc7-ecdb-4b6e-9c81-184b3282a6e1/query \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @openai.json

ModelWorks HTTP Adaptor

Adaptors of type MODELWORKS_HTTP provide direct, non‑streaming integration with the ModelWorks platform. Responses are returned as a single JSON document (application/json) rather than streamed. This is the adaptor type used by the in‑browser API Playground and for synchronous queries.

The request body uses the ModelWorks format — a top‑level context.version and an input object matching the circuit's query schema:

{
  "context": { "version": "8c5db2d9-d8a5-4752-a7a2-b31ae763d988" },
  "input": {
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  }
}

MCP Adaptor

Adaptors of type MCP implement the Model Context Protocol. Requests and responses are framed as newline‑delimited JSON (application/x-ndjson). MCP adaptors let you expose your circuit as a tool or resource that MCP‑compatible clients can invoke, and support input/output variable mappings between the MCP request and the circuit's variables.

XMCP Adaptor

Adaptors of type XMCP (Extended Model Context Protocol) are a non‑streaming variant that responds with a single JSON document (application/json). Like MCP, XMCP adaptors support variable mappings, but they do not produce an in‑flight query workboard.

None

An adaptor type of None means no adaptor is configured for that entry. Such an adaptor cannot be queried externally. Circuits that are only invoked via embedding or internal steps may use None.

Input / Output Mappings

Adaptors may declare a mapping object that translates variable names between the adaptor's request/response format and the circuit's own variables. A mapping is required for OpenAiSse adaptors, and optional (passthrough) for ModelworksSse, MODELWORKS_HTTP, and MCP.

Input Mappings

Input mappings rename fields from the incoming adaptor request into the circuit's input variables:

"mapping": {
  "input": [
    {
      "from_adapter_variable_name": "messages",
      "to_circuit_variable_name": "messages"
    }
  ]
}

Output Mappings

Output mappings rename the circuit's output variables into the adaptor's response format:

"mapping": {
  "output": [
    {
      "from_circuit_variable_name": "chat_completion_output",
      "to_adapter_variable_name": "choices",
      "mime_type": "application/json"
    }
  ]
}

Finding Your Adaptor UID

On any circuit’s Adaptors section in the UI, you’ll see a list of registered adaptors with their UIDs and types. Copy the UID to use in your query URL.

Note: Every adaptor endpoint that is SSE—responses are streamed as events until a "status":"complete" message arrives.

Error Handling

• 401 Unauthorized: Missing or invalid Bearer token.
• 403 Forbidden: You’re not the circuit owner (private/protected adaptors).
• 404 Not Found: Adaptor UID doesn’t exist.
• 400 Bad Request: Payload fails validation (schema mismatch).

Ensure your JSON matches the expected schema for each adaptor type before submitting.