Skip to main content

Get started with the SkillFlaw API

You can use the SkillFlaw API for programmatic interactions with SkillFlaw, such as the following:

  • Create and edit flows, including file management for flows.
  • Develop applications that use your flows.
  • Develop custom components.
  • Build SkillFlaw as a dependency of a larger application, codebase, or service.
  • Contribute to the overall SkillFlaw codebase.

To view and test all available endpoints, open the OpenAPI specification at your SkillFlaw deployment's /docs endpoint, such as http://localhost:7860/docs.

Try it

For an example of the SkillFlaw API in a script, see the quickstart.

The quickstart demonstrates how to get automatically generated code snippets for your flows, use a script to run a flow, and extract data from the SkillFlaw API response.

Form SkillFlaw API requests​

While individual options vary by endpoint, SkillFlaw API requests share some commonalities: a base URL, HTTP method, parameters, authentication, and, for many resource endpoints, explicit scope headers.

As an example, the following curl command calls the /v1/run endpoint and passes a runtime override (tweaks) to the flow's Chat Output component:


_14
curl --request POST \
_14
--url "$SKILLFLAW_URL/api/v1/run/$FLOW_ID?stream=false" \
_14
--header "Content-Type: application/json" \
_14
--header "x-api-key: $SKILLFLAW_API_KEY" \
_14
--data '{
_14
"input_value": "hello world!",
_14
"output_type": "chat",
_14
"input_type": "chat",
_14
"tweaks": {
_14
"ChatOutput-6zcZt": {
_14
"should_store_message": true
_14
}
_14
}
_14
}'

Base URL​

By default, local deployments serve the SkillFlaw API at http://localhost:7860/api.

Remotely hosted SkillFlaw deployments are available at the domain set by your hosting service, such as http://IP_OR_DNS/api.

Examples:

  • https://UUID.ngrok.app/api
  • http://IP_OR_DNS/api
  • http://IP_OR_DNS:PORT/api

Authentication​

Most /api/v1 endpoints require authentication with an active user session or an API key. For more information, see API keys and authentication.

As with any API, follow industry best practices for storing and referencing sensitive credentials. For example, you can set environment variables for your API keys and then reference those environment variables in your API requests.

Many resource-management endpoints also require explicit scope headers. For example, project-style endpoints expect at least tenant-id, and may also use business-id and is-self.

Methods, paths, and parameters​

SkillFlaw API requests use various methods, paths, path parameters, query parameters, and body parameters. The specific requirements and options depend on the endpoint that you want to call.

For example, to create a flow, you pass a JSON-formatted flow definition to POST /v1/flows. Then, to run your flow, you call POST /v1/run/$FLOW_ID with optional run parameters in the request body.

API versions​

The SkillFlaw API serves /v1 and /v2 endpoints.

Some endpoints only exist under a single version and some exist under both the /v1 and /v2 versions.

If a request fails or has an unexpected result, make sure your endpoint path has the correct version.

Set environment variables​

You can store commonly used values in environment variables to facilitate reuse, simplify token rotation, and securely reference sensitive values.

You can use any method you prefer to set environment variables, such as export, .env, zshrc, or .curlrc. Then, reference those environment variables in your API requests. For example:


_22
# Set environment variables
_22
export SKILLFLAW_API_KEY="sk..."
_22
export SKILLFLAW_URL="https://localhost:7860"
_22
export FLOW_ID="359cd752-07ea-46f2-9d3b-a4407ef618da"
_22
export PROJECT_ID="1415de42-8f01-4f36-bf34-539f23e47466"
_22
export TENANT_ID="3c0f3b3d-4d37-4f35-9a4a-b0f2db7c9f10"
_22
_22
# Use environment variables in API requests
_22
curl --request POST \
_22
--url "$SKILLFLAW_URL/api/v1/run/$FLOW_ID?stream=false" \
_22
--header "Content-Type: application/json" \
_22
--header "x-api-key: $SKILLFLAW_API_KEY" \
_22
--data '{
_22
"input_value": "hello world!",
_22
"output_type": "chat",
_22
"input_type": "chat",
_22
"tweaks": {
_22
"ChatOutput-6zcZt": {
_22
"should_store_message": true
_22
}
_22
}
_22
}'

Commonly used values in SkillFlaw API requests include your server URL, API key, flow IDs, project IDs, and, for scoped resource endpoints, tenant-id and business-id.

You can retrieve flow IDs from the API access pane, in a flow's URL, and with GET /flows.

Try some SkillFlaw API requests​

Once you have your SkillFlaw server URL, try calling these endpoints that return deployment metadata.

Health check​

Returns the health status of the database and chat services:


_10
curl -X GET \
_10
"$SKILLFLAW_URL/health_check" \
_10
-H "accept: application/json"

Result

_10
{
_10
"status": "ok",
_10
"chat": "ok",
_10
"db": "ok"
_10
}

SkillFlaw also provides GET /health. That endpoint is served before the application is fully initialized, so GET /health_check is the better readiness check.

Get version​

Returns the current SkillFlaw API version:


_10
curl -X GET \
_10
"$SKILLFLAW_URL/api/v1/version" \
_10
-H "accept: application/json"

Result

_10
{
_10
"version": "1.6.0",
_10
"main_version": "1.6.0",
_10
"package": "SkillFlaw"
_10
}

Get configuration​

Returns configuration details for your SkillFlaw deployment. Requires authentication.


_10
curl -X GET \
_10
"$SKILLFLAW_URL/api/v1/config" \
_10
-H "accept: application/json" \
_10
-H "x-api-key: $SKILLFLAW_API_KEY"

Result

_20
{
_20
"feature_flags": {
_20
"mvp_components": false
_20
},
_20
"serialization_max_items_length": 1000,
_20
"serialization_max_text_length": 6000,
_20
"frontend_timeout": 0,
_20
"auto_saving": true,
_20
"auto_saving_interval": 1000,
_20
"health_check_max_retries": 5,
_20
"max_file_size_upload": 1024,
_20
"webhook_polling_interval": 5000,
_20
"public_flow_cleanup_interval": 3600,
_20
"public_flow_expiration": 86400,
_20
"event_delivery": "streaming",
_20
"webhook_auth_enable": false,
_20
"voice_mode_available": false,
_20
"default_folder_name": "Starter Project",
_20
"hide_getting_started_progress": false
_20
}

Get all components​

Returns a dictionary of all registered components. Requires authentication.


_10
curl -X GET \
_10
"$SKILLFLAW_URL/api/v1/all" \
_10
-H "accept: application/json" \
_10
-H "x-api-key: $SKILLFLAW_API_KEY"

Available endpoints​

Because SkillFlaw can run as either an IDE-style deployment or a runtime-oriented backend, it serves endpoints for both application execution and internal frontend orchestration. Many endpoints exist to support the web editor, project management, scoped resources, or debugging flows in the Playground. Unless you are contributing to the SkillFlaw codebase, you won't directly call most internal orchestration endpoints.

For application development, the most commonly used endpoints are the /run and /webhook flow trigger endpoints. For some use cases, you might also use /files, /projects, /logs, or custom-component validation endpoints.

To help you explore the available endpoints, the following lists are sorted by primary use case, although some endpoints might support multiple use cases.

The following endpoints are useful for developing applications with SkillFlaw and administering deployments with one or more users. You will most often use the flow trigger endpoints. Other endpoints are helpful for specific use cases, such as administration and flow management in runtime deployments that don't have a visual editor.

  • Flow trigger endpoints:

    • POST /v1/run/{flow_id_or_name}: Run a flow.
    • POST /v1/run/advanced/{flow_id}: Advanced run with explicit inputs, outputs, tweaks, and optional session_id.
    • POST /v1/webhook/{flow_id_or_name}: Trigger a flow via webhook payload.

  • OpenAI Responses API:

    • POST /v1/responses: Execute flows using an OpenAI-compatible request format.

  • Deployment details:

    • GET /v1/version: Return SkillFlaw version. See Get version.
    • GET /v1/config: Return deployment configuration. See Get configuration.
    • GET /health_check: Health check endpoint that validates database and chat service connectivity. Returns 500 status if any service is unavailable.
    • GET /logs: Return buffered log lines near a timestamp.
    • GET /logs-stream: Stream buffered logs with SSE.

  • Projects endpoints:

    • POST /v1/projects/: Create a project.
    • GET /v1/projects/: List projects.
    • GET /v1/projects/{project_id}: Read a project.
    • PATCH /v1/projects/{project_id}: Update project info and membership.
    • DELETE /v1/projects/{project_id}: Delete a project.
    • GET /v1/projects/download/{project_id}: Export all flows in a project as ZIP.
    • POST /v1/projects/upload/: Import a project definition JSON file.
    • POST /v1/projects/{project_id}/invoke: Invoke a project online.
    • GET|POST|DELETE /v1/projects/{project_id}/skills: Read, attach, or detach project skills.
    • GET|POST|DELETE /v1/projects/{project_id}/auth/users: Read or update project user authorization.
    • GET|POST|DELETE /v1/projects/{project_id}/auth/groups: Read or update project group authorization.
    • GET|POST|DELETE /v1/projects/{project_id}/auth/orgs: Read or update project organization authorization.
    • GET /v1/starter-projects/: Return a list of templates.

  • Files endpoints:

    • Files (v1)
      • POST /v1/files/upload/{flow_id}: Upload a file to a specific flow.
      • GET /v1/files/download/{flow_id}/{file_name}: Download a file from a flow.
      • GET /v1/files/images/{flow_id}/{file_name}: Stream an image from a flow.
      • GET /v1/files/profile_pictures/{folder_name}/{file_name}: Get a profile picture asset.
      • GET /v1/files/profile_pictures/list: List available profile picture assets.
      • GET /v1/files/list/{flow_id}: List files for a flow.
      • DELETE /v1/files/delete/{flow_id}/{file_name}: Delete a file from a flow.
    • Files (v2)
      • POST /v2/files (alias /v2/files/): Upload a file in the current scope.
      • GET /v2/files (alias /v2/files/): List files in the current scope.
      • DELETE /v2/files/batch/: Delete multiple files by IDs.
      • POST /v2/files/batch/: Download multiple files as a ZIP by IDs.
      • GET /v2/files/{file_id}: Download a file by ID (or return raw content internally).
      • PUT /v2/files/{file_id}: Edit a file name by ID.
      • DELETE /v2/files/{file_id}: Delete a file by ID.
      • DELETE /v2/files (alias /v2/files/): Delete all files in the current scope.

  • API keys and authentication:

    • GET /v1/api_key/: List API keys for the current user.
    • POST /v1/api_key/: Create a new API key.
    • DELETE /v1/api_key/{api_key_id}: Delete an API key.
    • POST /v1/api_key/store: Save an encrypted Store API key (cookie set).

  • Flow management endpoints:

    • POST /v1/flows/: Create a flow.
    • GET /v1/flows/: List flows (supports pagination and filters).
    • GET /v1/flows/{flow_id}: Read a flow by ID.
    • GET /v1/flows/public_flow/{flow_id}: Read a public flow by ID.
    • PATCH /v1/flows/{flow_id}: Update a flow.
    • DELETE /v1/flows/{flow_id}: Delete a flow.
    • POST /v1/flows/batch/: Create multiple flows.
    • POST /v1/flows/upload/: Import flows from a JSON file.
    • DELETE /v1/flows/: Delete multiple flows by IDs.
    • POST /v1/flows/download/: Export flows to a ZIP file.
    • GET /v1/flows/flow_template/: List visible flow templates.

  • Users endpoints:

    • POST /v1/users/: Add a user (superuser required when auth enabled).
    • GET /v1/users/whoami: Return the current authenticated user.
    • GET /v1/users/: List all users (superuser required).
    • PATCH /v1/users/{user_id}: Update a user (with role checks).
    • PATCH /v1/users/{user_id}/reset-password: Reset own password.
    • DELETE /v1/users/{user_id}: Delete a user (cannot delete yourself).

  • Custom components: You might use these endpoints when developing custom SkillFlaw components for your own use or to share with your team:

    • GET /v1/all: Return all available component types. See Get all components.
    • POST /v1/custom_component: Build a custom component from code and return its node.
    • POST /v1/custom_component/update: Update an existing custom component's build config and outputs.
    • POST /v1/validate/code: Validate a Python code snippet for a custom component.
    • POST /v1/validate/prompt: Validate a prompt payload.

Next steps​