API Reference

Complete REST API v1 documentation. Manage workflows, executions, webhooks, and more programmatically with full CRUD operations and real-time event publishing.

REST API v1 OpenAPI 3.1 JSON

Authentication

All API requests require authentication via one of the following methods:

Method	Header	Example
API Key	`X-Api-Key`	`X-Api-Key: ahub_k1_abc123...`
Bearer Token	`Authorization`	`Authorization: Bearer ahub_k1_abc123...`

Base URL

https://your-domain.com/api/v1

Status Codes & Error Format

Code	Meaning
`200`	Success — resource returned
`201`	Created — resource created successfully
`202`	Accepted — async operation queued
`204`	No Content — successful deletion
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — insufficient permissions
`422`	Validation Error — invalid request body
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error

Error Response Format

JSON Error Response

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "fields": {
      "name": ["The name field is required."],
      "trigger_type": ["The selected trigger type is invalid."]
    }
  }
}

Rate Limiting

Rate limit information is included in response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Requests remaining in current window
`Retry-After`	Seconds until rate limit resets (only on 429)

Idempotency

For safe retries on create operations, include an Idempotency-Key header:

Idempotency Header

Idempotency-Key: unique-request-id-12345

The key has a TTL of 10 minutes. Duplicate requests within that window return the original response without re-executing the operation.

Events

POST /v1/events

Publish a domain event to trigger event-driven workflows.

Field	Type	Required	Description
`event`	string	Yes	Event name (e.g., `order.created`)
`payload`	object	Yes	Event data passed to workflows

curl — Publish Event

curl -X POST https://your-domain.com/api/v1/events \
  -H "X-Api-Key: ahub_k1_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order.created",
    "payload": {
      "order_id": "ORD-12345",
      "customer_email": "john@example.com",
      "total": 99.99
    }
  }'

Response — 202 Accepted

{
  "message": "Event published successfully",
  "event": "order.created",
  "workflows_triggered": 2
}

Workflows

GET /v1/workflows

List all workflows (paginated).

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	15	Items per page (max 100)
`status`	string	—	Filter by status: `active`, `inactive`, `draft`
`search`	string	—	Search by name or description

curl — List Workflows

curl -X GET "https://your-domain.com/api/v1/workflows?page=1&per_page=10" \
  -H "X-Api-Key: ahub_k1_your_key_here"

POST /v1/workflows

Create a new workflow.

curl — Create Workflow

curl -X POST https://your-domain.com/api/v1/workflows \
  -H "X-Api-Key: ahub_k1_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Confirmation",
    "description": "Send confirmation email on new orders",
    "trigger_type": "event",
    "trigger_config": {
      "event": "order.created"
    },
    "status": "active",
    "nodes": [...],
    "edges": [...]
  }'

GET /v1/workflows/{id}

Get a single workflow with its complete node and edge configuration.

PUT /v1/workflows/{id}

Update an existing workflow (full replacement of nodes/edges).

DELETE /v1/workflows/{id}

Delete a workflow. Returns 204 No Content on success.

POST /v1/workflows/{id}/execute

Manually trigger a workflow execution with optional input data.

curl — Execute Workflow

curl -X POST https://your-domain.com/api/v1/workflows/wf_abc123/execute \
  -H "X-Api-Key: ahub_k1_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "customer_email": "jane@example.com",
      "order_id": "ORD-67890"
    }
  }'

Response — 202 Accepted

{
  "execution_id": "exec_xyz789",
  "workflow_id": "wf_abc123",
  "status": "running",
  "started_at": "2026-07-18T10:30:00Z"
}

Executions

GET /v1/executions

List workflow executions (paginated). Supports filtering by workflow ID, status, and date range.

Parameter	Type	Description
`workflow_id`	string	Filter by workflow
`status`	string	`completed`, `failed`, `running`, `cancelled`
`from`	datetime	Start date filter (ISO 8601)
`to`	datetime	End date filter (ISO 8601)

GET /v1/executions/{id}

Get execution details including all step results, timing, and error messages.

Response — Execution Details

{
  "id": "exec_xyz789",
  "workflow_id": "wf_abc123",
  "workflow_name": "Order Confirmation",
  "status": "completed",
  "started_at": "2026-07-18T10:30:00Z",
  "completed_at": "2026-07-18T10:30:02Z",
  "duration_ms": 2043,
  "trigger": "api",
  "steps": [
    {
      "node_id": "node_1",
      "node_type": "email_send",
      "status": "completed",
      "started_at": "2026-07-18T10:30:00Z",
      "completed_at": "2026-07-18T10:30:02Z",
      "output": { "message_id": "msg_abc" }
    }
  ]
}

POST /v1/executions/{id}/retry

Retry a failed execution from the point of failure.

Webhooks

GET /v1/webhooks

List all registered webhooks for the current organization.

POST /v1/webhooks

Create a new outbound webhook subscription.

curl — Create Webhook

curl -X POST https://your-domain.com/api/v1/webhooks \
  -H "X-Api-Key: ahub_k1_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/automation-hub",
    "events": ["execution.completed", "execution.failed"],
    "secret": "your_webhook_secret"
  }'

GET /v1/webhooks/{id}

Get webhook details.

PUT /v1/webhooks/{id}

Update webhook URL, events, or secret.

DELETE /v1/webhooks/{id}

Delete a webhook. Returns 204 No Content.

API Keys

GET /v1/api-keys

List all API keys (shows metadata only — keys are never returned after creation).

POST /v1/api-keys

Create a new API key. The plain-text key is returned only once in the response.

curl — Create API Key

curl -X POST https://your-domain.com/api/v1/api-keys \
  -H "X-Api-Key: ahub_k1_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Integration",
    "permissions": ["workflows.create", "executions.view", "events.publish"]
  }'

Response — 201 Created

{
  "id": "key_abc123",
  "name": "Production Integration",
  "key": "ahub_k1_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
  "permissions": ["workflows.create", "executions.view", "events.publish"],
  "created_at": "2026-07-18T10:00:00Z",
  "message": "Store this key securely. It will not be shown again."
}

Store Your Key Immediately

The plain-text API key is only shown once at creation. If you lose it, you must revoke the key and create a new one.

POST /v1/api-keys/{id}/revoke

Revoke an API key. The key immediately becomes invalid for all future requests.

Node Types

GET /v1/node-types

List all available node types with their input/output schemas and configuration options.

curl — List Node Types

curl -X GET https://your-domain.com/api/v1/node-types \
  -H "X-Api-Key: ahub_k1_your_key_here"

Audit Logs

GET /v1/audit-logs

Query organization audit logs. Requires audit.view permission.

Parameter	Type	Description
`user_id`	string	Filter by user
`action`	string	Filter by action (created, updated, deleted, etc.)
`entity_type`	string	Filter by entity type
`from`	datetime	Start date (ISO 8601)
`to`	datetime	End date (ISO 8601)
`per_page`	integer	Items per page (default 25, max 100)

curl — Query Audit Logs

curl -X GET "https://your-domain.com/api/v1/audit-logs?action=created&from=2026-07-01T00:00:00Z" \
  -H "X-Api-Key: ahub_k1_your_key_here"

Pagination

All list endpoints return paginated responses with the following structure:

Paginated Response Structure

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 72
  },
  "links": {
    "first": "/api/v1/workflows?page=1",
    "last": "/api/v1/workflows?page=5",
    "prev": null,
    "next": "/api/v1/workflows?page=2"
  }
}