REST API

The web service exposes a REST API at /api/v1/. All flow operations in the web UI use this API, and you can call it directly for automation.

Interactive API documentation is available at /api/docs (Swagger UI) with the full OpenAPI spec at /api/docs/spec.

Authentication

API endpoints that interact with ServiceNow require a session. Create one by configuring your connection in the Settings panel or by calling the auth test endpoint.

Endpoints that don't need a ServiceNow connection (validate, diagram, samples) work without authentication.

Endpoints

Flows

Method	Path	Description
GET	/api/v1/flows	List all flows on the connected instance
GET	/api/v1/flows/{sys_id}	Get a flow's full details
GET	/api/v1/flows/{sys_id}/yaml	Export a flow as YAML
POST	/api/v1/flows	Create a new flow from YAML
PUT	/api/v1/flows/{sys_id}	Update an existing flow from YAML

Offline (no ServiceNow connection needed)

Method	Path	Description
POST	/api/v1/flows/validate	Validate a YAML flow definition
POST	/api/v1/flows/diagram	Generate a flow diagram from YAML
GET	/api/v1/samples	List available sample YAML files

Utility

Method	Path	Description
POST	/api/v1/auth/test	Test ServiceNow connection credentials
POST	/api/v1/flows/edit-status	Check if a flow is safe to edit
GET	/healthz	Health check

Export with Identity Metadata

When exporting for later updates, add ?with_uuid=true to include step IDs and metadata:

GET /api/v1/flows/{sys_id}/yaml?with_uuid=true

The exported YAML will include sys_id, step id fields, and a _metadata section needed for the update workflow.

Validate

Send a YAML body to validate offline:

POST /api/v1/flows/validate
Content-Type: text/yaml

schema: nebula
name: My Flow
type: flow
...

Returns validation errors (if any) without contacting ServiceNow.