Build endpoints

info

The /build endpoints are used by SkillFlaw's frontend visual editor and contributor tooling. These endpoints are internal orchestration APIs, not the recommended runtime interface for application integrations.

Don't use these endpoints to run flows in applications that use your SkillFlaw flows. To run flows in your apps, see Flow trigger endpoints.

The /build endpoints support SkillFlaw's visual editor for building flows and returning execution events. You might need to use or understand these endpoints when contributing to the SkillFlaw codebase.

Build flow and stream events

The common workflow is:

POST /api/v1/build/{flow_id}/flow to start a build job.
Receive a job_id.
GET /api/v1/build/{job_id}/events to stream or poll the build events.

Authenticated build routes require an active SkillFlaw user session or another accepted authenticated request.

Send a POST request to the /build/$FLOW_ID/flow endpoint:

_10curl -X POST \ _10 "$SKILLFLAW_URL/api/v1/build/$FLOW_ID/flow" \ _10 -H "accept: application/json" \ _10 -H "Content-Type: application/json" \ _10 -H "x-api-key: $SKILLFLAW_API_KEY" \ _10 -d '{ _10 "inputs": { _10 "input_value": "Tell me a story" _10 } _10 }'

Result
_10{ _10 "job_id": "123e4567-e89b-12d3-a456-426614174000" _10}
After receiving a job ID from the build endpoint, use the /build/$JOB_ID/events endpoint to stream the execution results:

_10curl -X GET \ _10 "$SKILLFLAW_URL/api/v1/build/123e4567-e89b-12d3-a456-426614174000/events" \ _10 -H "accept: application/json" \ _10 -H "x-api-key: $SKILLFLAW_API_KEY"

Result
_10{"event": "vertices_sorted", "data": {"ids": ["ChatInput-XtBLx"], "to_run": ["Prompt-x74Ze", "ChatOutput-ylMzN", "ChatInput-XtBLx", "OpenAIModel-d1wOZ"]}} _10 _10{"event": "add_message", "data": {"timestamp": "2025-03-03T17:42:23", "sender": "User", "sender_name": "User", "session_id": "d2bbd92b-187e-4c84-b2d4-5df365704201", "text": "Tell me a story", "files": [], "error": false, "edit": false, "properties": {"text_color": "", "background_color": "", "edited": false, "source": {"id": null, "display_name": null, "source": null}, "icon": "", "allow_markdown": false, "positive_feedback": null, "state": "complete", "targets": []}, "category": "message", "content_blocks": [], "id": "28879bd8-6a68-4dd5-b658-74d643a4dd92", "flow_id": "d2bbd92b-187e-4c84-b2d4-5df365704201"}} _10 _10// ... Additional events as the flow executes ... _10 _10{"event": "end", "data": {}}

GET /api/v1/build/{job_id}/events uses the event_delivery query parameter. The default is streaming. To fetch newline-delimited JSON without a long-lived stream, set ?event_delivery=polling.


_10curl -X GET \
_10  "$SKILLFLAW_URL/api/v1/build/123e4567-e89b-12d3-a456-426614174000/events?event_delivery=polling" \
_10  -H "accept: application/json" \
_10  -H "x-api-key: $SKILLFLAW_API_KEY"

If you pass event_delivery=direct to POST /api/v1/build/{flow_id}/flow, SkillFlaw returns the event stream immediately instead of a job_id wrapper. The frontend test harness uses this mode; most integrations should still prefer the standard job_id flow above.

Build headers

Header	Info	Example
Content-Type	Required. Specifies the JSON format.	"application/json"
accept	Optional. Specifies the response format.	"application/json"
x-api-key	Optional for authenticated automation requests.	"sk-..."

Build parameters

Parameter	Type	Description
inputs	object	Optional. Input values for flow components.
data	object	Optional. Flow data to override stored configuration.
files	array[string]	Optional. List of file paths to use.
start_component_id	string	Optional. ID of the component where execution should start.
stop_component_id	string	Optional. ID of the component where execution should stop.
log_builds	Boolean	Whether to record build logs. Default: `true`.
flow_name	string	Optional. Flow name override used by internal tooling.
event_delivery	string	Optional. `polling`, `streaming`, or `direct`, depending on endpoint.

Set start and stop points

The /build endpoint accepts optional values for start_component_id and stop_component_id to control where the flow run starts and stops. Setting stop_component_id for a component triggers the same behavior as clicking Run component on that component in the visual editor: The specified component and all dependent components leading up to that component will run.

The following example stops flow execution at an OpenAI component:


_10curl -X POST \
_10  "$SKILLFLAW_URL/api/v1/build/$FLOW_ID/flow" \
_10  -H "accept: application/json" \
_10  -H "Content-Type: application/json" \
_10  -H "x-api-key: $SKILLFLAW_API_KEY" \
_10  -d '{"stop_component_id": "OpenAIModel-Uksag"}'

Override flow parameters

The /build endpoint also accepts data directly, instead of using the values stored in the SkillFlaw database. This is useful for running flows without having to pass custom values through the visual editor.


_15curl -X POST \
_15  "$SKILLFLAW_URL/api/v1/build/$FLOW_ID/flow" \
_15  -H "accept: application/json" \
_15  -H "Content-Type: application/json" \
_15  -H "x-api-key: $SKILLFLAW_API_KEY" \
_15  -d '{
_15    "data": {
_15      "nodes": [],
_15      "edges": []
_15    },
_15    "inputs": {
_15      "input_value": "Your custom input here",
_15      "session": "session_id"
_15    }
_15  }'

Result


_10{ "job_id": "0bcc7f23-40b4-4bfa-9b8a-a44181fd1175" }

Other build endpoints

SkillFlaw also exposes related build endpoints used by the editor and public-flow experience:

POST /api/v1/build/template/{template_id}/flow
GET /api/v1/build/template/{build_id}/events
POST /api/v1/build/{job_id}/cancel
POST /api/v1/build/template/{build_id}/cancel
POST /api/v1/build_public_tmp/{flow_id}/flow
GET /api/v1/build_public_tmp/{job_id}/events
POST /api/v1/build_public_tmp/{job_id}/cancel

The build_public_tmp routes are specifically for public-flow execution and do not use the same authentication requirement as the authenticated editor routes.

Build flow and stream events​

Build headers​

Build parameters​

Set start and stop points​

Override flow parameters​

Other build endpoints​

See also​