API Reference

The stepIQ REST API lets you manage pipelines, trigger runs, and query results programmatically. All endpoints return JSON.

Base URL: https://api.stepiq.sh/v1

Authentication

All API requests must include an authorization header. Two methods are supported:

Method	Header	How to get
JWT Token	`Authorization: Bearer <jwt_token>`	`POST /api/auth/login`
API Key	`X-API-Key: sk_live_xxxxxxxx`	Settings - API Keys

Auth endpoints

POST/api/auth/registerEmail + password signup

POST/api/auth/loginReturns JWT token

POST/api/auth/refreshRefresh JWT token

POST/api/auth/forgot-passwordSend reset email

Pipelines

GET/api/pipelinesList user's pipelines

POST/api/pipelinesCreate pipeline (JSON or YAML body)

GET/api/pipelines/:idGet pipeline details

PUT/api/pipelines/:idUpdate pipeline (creates new version)

DELETE/api/pipelines/:idArchive pipeline (soft delete)

Execution

POST/api/pipelines/:id/runTrigger a run

POST/api/webhooks/:pipelineIdTrigger a run via inbound webhook (API key)

GET/api/runsList runs (filterable)

GET/api/runs/:idGet run details + step executions

GET/api/runs/:id/streamSSE stream for real-time updates

POST/api/runs/:id/cancelCancel a running pipeline

Schedules

GET/api/pipelines/:id/schedulesList schedules

POST/api/pipelines/:id/schedulesCreate schedule

POST/api/schedules/:id/enableEnable schedule

GET/api/schedules/upcomingList next scheduled runs

User & Secrets

GET/api/user/meCurrent user profile

GET/api/user/usageUsage stats (tokens, cost, runs)

GET/api/user/api-keysList API keys (metadata only)

POST/api/user/api-keysCreate API key

DELETE/api/user/api-keys/:idRevoke API key

POST/api/user/secretsCreate/update encrypted secret

Models

Use model discovery endpoints to list supported providers and model capabilities before pipeline execution.

Webhooks

Use webhooks to trigger pipelines from external systems and to receive pipeline output in your own services.

Plan availability: webhooks are available on starter, pro, and enterprise plans. They are not available on the free plan.

Inbound webhook trigger

POST/api/webhooks/:pipelineIdCreate a pending run and enqueue execution

Item	Details
Authentication	`X-API-Key: sk_live_...`
Payload format	`{"input_data":{...}}` (recommended) or top-level JSON object
Success	`202 Accepted` with run metadata
Validation	If `input.schema` exists, payload must match it

Request example

curl -X POST "https://api.stepiq.sh/v1/api/webhooks/<pipeline-id>" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_xxxxxxxx" \
  -d '{"input_data":{"topic":"AI agents","language":"en"}}'

Response example (202)

{
  "accepted": true,
  "run_id": "b0b0b0b0-c1c1-d2d2-e3e3-f4f4f4f4f4f4",
  "status": "pending",
  "pipeline_id": "a0a0a0a0-b1b1-c2c2-d3d3-e4e4e4e4e4e4"
}

Status	When
`401`	Missing or invalid API key
`404`	Pipeline not found or not active
`422`	Payload does not match `input.schema`

Outbound webhook delivery

Configure this in pipeline output delivery (type: webhook). stepIQ sends an event when a run completes.

Item	Details
Trigger	Run completion
Retry policy	Up to 4 attempts, exponential backoff (1s, 2s, 4s)
Timeout	10 seconds per attempt
Retry conditions	Network errors and `5xx` responses
Required config	`signing_secret_name` in webhook delivery target

Sent headers

Header	Value
`Content-Type`	`application/json`
`X-StepIQ-Event`	`pipeline.run.completed`
`X-StepIQ-Timestamp`	Unix seconds
`X-StepIQ-Signature`	`v1=<hmac_sha256_hex>`

Payload example

{
  "event": "pipeline.run.completed",
  "pipeline": { "id": "...", "version": 1, "name": "My Pipeline" },
  "run": {
    "id": "...",
    "status": "completed",
    "trigger_type": "webhook",
    "started_at": "2026-02-27T10:00:00.000Z",
    "completed_at": "2026-02-27T10:00:04.000Z"
  },
  "input": { "...": "..." },
  "output": { "...": "..." },
  "meta": { "sent_at": "2026-02-27T10:00:04.500Z", "attempt": 1 }
}

Signature verification: HMAC_SHA256(signing_secret, "<timestamp>.<raw_json_body>") and compare with X-StepIQ-Signature.

Receiver behavior: return 2xx after success, 5xx to request retry, and deduplicate by run.id.