14 api lab

API Lab

API Lab is the second mode of the Auto tab. Click API Lab in the header (next to Auto Builder). It is an in-app HTTP workbench for the same /v1/* contract the fractalflow api server exposes to external machines.

Use it to inspect catalogs, validate payloads, send requests against a local or remote API base URL, and copy working JSON into scripts.

API Lab endpoint selection and request controls.

Layout

Left:

• Endpoint group combo (ApiEndpointGroups)
• Endpoint list: each row shows METHOD /v1/... and a label
• Read-only metadata box (schema / description)
• Reload endpoint template — restore the canned body for the selected route
• Copy API Lab request — copy the current request to the clipboard

Center — heading Request JSON:

Control	Role
Base URL	Server origin, for example http://127.0.0.1:8080.
Bearer token	Same secret you passed to fractalflow api --token.
Request path or absolute URL	Path with placeholders such as {id:long}; add query parameters here.
Send	Execute the request.
Cancel	Abort the in-flight call.
Validate	Schema-check the JSON without sending.
Paste / Import / Export	Clipboard or file round-trip for the body.

Destructive routes may show a confirmation strip; type the instruction text to enable send.

Right / lower:

• Response body and status
• Payload history expander
• Helper insert/copy: Insert helper, Copy helper

Auto Builder also has Send to API Lab on planned payloads so a Preview plan can become a live request.

What the catalog covers

Groups include (labels in the UI):

• Formula / camera / visual / track / family-pack / seed-preset catalogs
• Clip post effects and event kinds (shared Clip Studio / procedural)
• Clip export formats and procedural direct export formats
• Compositions, params, render
• Videos And Clips — video library, probe, export, cleanup
• Procedural Video — Psychedelia Live, Animation Lab, and Shader Lab project, preview, persist, render, transform
• Shader Lab Quick Create and visual-only public Shadertoy import
• Automation seed-plan / composition-plan / clip-job and procedural auto plan/render/batch

The raw procedural API can run the same seeded builder operations and locks as all three visual tabs. Imported API keys are request-only and are not stored in projects.

Typical API Lab loop

1. Start the server in another terminal: fractalflow api --port 8080 --bind 127.0.0.1 (see CLI and API). Leave that process running. By default it prints a generated bearer token.
2. Open API Lab. Set Base URL to http://127.0.0.1:8080 and paste that server's token into Bearer token. Otherwise a valid request receives 401 Unauthorized.
3. Pick a GET catalog endpoint, Send, confirm JSON.
4. Pick a POST such as procedural auto plan, Validate, then Send.
5. Export the working body next to your scripts.

Payload shapes, field names, and troubleshooting live in docs/api-cli-automation-guide.md. This usage manual only covers how to run the same operations from the UI and CLI.

Replace path placeholders such as {id:long} with a real numeric ID before sending. Validate checks the request body; it does not start a server, authenticate, or guarantee that a referenced file/composition exists. For connection failures, check the server process and base URL. For 401, check the token. Read the response error/code for validation failures, and cancel long jobs through their owning job endpoint rather than assuming that closing the response pane cancels the work.

API Lab: a successful local version request and HTTP 200 response.

Continue: CLI and API.