API Playground & Samples

The API Playground provides a live, in-browser interface for querying your circuit versions. It enables developers to:

• Select a version: Switch between published versions of your circuit to test specific releases.
• Inspect inputs/outputs: View and edit the JSON payload schema derived from your circuit’s definition.
• Submit queries: Send test requests directly to the circuit engine and watch real-time status updates (request, waiting, result).
• View artifacts: Download or preview generated artifacts (images, blobs) produced by your circuit.

This immediate feedback loop helps both authors and integrators verify that inputs, outputs, and side-effects behave as expected before embedding or automating calls.

Playground Features

1. Version Selector

   • Choose any available circuit version to target your request.
   • Ensures you can reproduce or debug against past releases without redeploying.

2. Request Editor

   • Auto-generated example payload based on your circuit’s input schema.
   • Inline JSON editing with validation hints to ensure required fields and types are correct.

3. Submit & Monitor

   • Hit Submit to invoke the circuit.

   • Real‑time visual indicators for each step:

     • A. Query Request: shows the exact JSON sent.
     • B. Query Response: initial acknowledgement from the engine.
     • C. Waiting for Result: polling status when asynchronous work is in progress.
     • D. Query Result: the final result document.

4. Artifacts Section

   • Any returned URLs (e.g., generated images or files) appear below the result.
   • Inline previews for common media types and direct download links.

Sample Runs

The Sample Runs tab surfaces real executions provided by the circuit’s author:

• Author-provided examples: Pre‑populated requests and responses demonstrate typical usage.
• Quick onboarding: Developers can click any sample run to see both the exact request payload (curl/wget examples) and the response schema.
• Copy commands: One-click “Copy curl” or “Copy wget” to bootstrap integration scripts.

Sample runs are invaluable for:

• Validating edge cases and optional fields.
• Ensuring that response parsing logic in client libraries aligns with actual engine outputs.
• Accelerating time‑to‑first‑query for new consumers of your circuit.

Enabling the Playground

• Public circuits: Playground is available to all visitors; no authentication needed for public endpoints.
• Protected/private circuits: Authors must light the circuit (run 3 successful runs) to promote it to a running state. Visiting integrators will then see its Playground enabled once the version reaches a healthy status.

Note: The playground requires a MODELWORKS_HTTP adaptor to submit queries. The circuit must have an HTTP adaptor configured, or the playground will be unable to dispatch requests to the engine.

Tip: Running a quick sample run after publishing a new version ensures that the Playground accurately reflects your latest definitions and that any downstream cache or schema generation is up-to-date.

---

For detailed API reference and generated schema documentation, visit the Documentation tab in each repository.