Advanced10 min

API Reference

Complete reference for our REST API. Build custom integrations and automate your workflows.

Getting Started

Base URL

https://api.yourapp.com/v1

Authentication

All requests require an API key:

curl https://api.yourapp.com/v1/workflows \
  -H "Authorization: Bearer YOUR_API_KEY"

Getting an API Key

  1. Go to Settings > API Keys
  2. Click Create Key
  3. Name your key
  4. Copy and store securely

Response Format

Success Response

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid workflow ID",
    "details": { ... }
  }
}

Rate Limits

Limits by Plan

| Plan | Requests/min | Requests/day | |------|--------------|--------------| | Free | 60 | 1,000 | | Starter | 120 | 10,000 | | Pro | 300 | 50,000 | | Business | 600 | 200,000 |

Rate Limit Headers

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1640000000

Workflows

List Workflows

GET /workflows

Query Parameters:

  • page - Page number (default: 1)
  • limit - Items per page (default: 20)
  • status - Filter by status: draft, published
  • search - Search by name

Response:

{
  "data": [
    {
      "id": "wf_123",
      "name": "Lead Notification",
      "status": "published",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-20T15:30:00Z"
    }
  ],
  "meta": { "total": 25 }
}

Get Workflow

GET /workflows/:id

Response:

{
  "data": {
    "id": "wf_123",
    "name": "Lead Notification",
    "description": "Notify sales on new leads",
    "status": "published",
    "nodes": [...],
    "edges": [...],
    "variables": {...},
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Create Workflow

POST /workflows

Body:

{
  "name": "New Workflow",
  "description": "Workflow description",
  "nodes": [],
  "edges": []
}

Update Workflow

PATCH /workflows/:id

Body:

{
  "name": "Updated Name",
  "status": "published"
}

Delete Workflow

DELETE /workflows/:id

Workflow Execution

Execute Workflow

POST /workflows/:id/execute

Body:

{
  "input": {
    "email": "user@example.com",
    "name": "John Doe"
  }
}

Response:

{
  "data": {
    "execution_id": "exec_456",
    "status": "running",
    "started_at": "2024-01-20T15:30:00Z"
  }
}

Get Execution Status

GET /executions/:id

Response:

{
  "data": {
    "id": "exec_456",
    "workflow_id": "wf_123",
    "status": "completed",
    "started_at": "2024-01-20T15:30:00Z",
    "completed_at": "2024-01-20T15:30:05Z",
    "output": {...},
    "logs": [...]
  }
}

List Executions

GET /workflows/:id/executions

Query Parameters:

  • status - Filter: pending, running, completed, failed
  • from - Start date (ISO 8601)
  • to - End date (ISO 8601)

Forms

List Forms

GET /forms

Get Form

GET /forms/:id

Create Form

POST /forms

Body:

{
  "name": "Contact Form",
  "fields": [
    {
      "name": "email",
      "type": "email",
      "required": true
    },
    {
      "name": "message",
      "type": "textarea",
      "required": true
    }
  ]
}

Submit Form

POST /forms/:id/submissions

Body:

{
  "data": {
    "email": "user@example.com",
    "message": "Hello!"
  }
}

Get Submissions

GET /forms/:id/submissions

Credentials

List Credentials

GET /credentials

Note: Secret values are never returned.

Create Credential

POST /credentials

Body:

{
  "name": "Slack Bot Token",
  "type": "api_key",
  "value": "xoxb-your-token"
}

Delete Credential

DELETE /credentials/:id

Integrations

List Connected Integrations

GET /integrations

Test Integration

POST /integrations/:id/test

Webhooks

Create Webhook

POST /webhooks

Body:

{
  "url": "https://yoursite.com/webhook",
  "events": ["workflow.executed", "form.submitted"],
  "secret": "your-webhook-secret"
}

List Webhooks

GET /webhooks

Delete Webhook

DELETE /webhooks/:id

See Webhook API for event details.

Error Codes

Common Errors

| Code | Description | |------|-------------| | UNAUTHORIZED | Invalid or missing API key | | FORBIDDEN | Insufficient permissions | | NOT_FOUND | Resource not found | | VALIDATION_ERROR | Invalid request data | | RATE_LIMITED | Too many requests | | INTERNAL_ERROR | Server error |

Handling Errors

const response = await fetch('/api/workflows');
const data = await response.json();

if (!data.success) {
  switch (data.error.code) {
    case 'RATE_LIMITED':
      await delay(60000);
      return retry();
    case 'UNAUTHORIZED':
      return refreshToken();
    default:
      throw new Error(data.error.message);
  }
}

SDKs

JavaScript/TypeScript

npm install @yourapp/sdk

import { Client } from '@yourapp/sdk';

const client = new Client('YOUR_API_KEY');

const workflows = await client.workflows.list();
await client.workflows.execute('wf_123', { input: {...} });

Python

pip install yourapp-sdk

from yourapp import Client

client = Client('YOUR_API_KEY')

workflows = client.workflows.list()
client.workflows.execute('wf_123', input={...})

Pagination

Cursor-Based

For large datasets:

GET /executions?cursor=abc123&limit=50

Response:

{
  "data": [...],
  "meta": {
    "next_cursor": "xyz789",
    "has_more": true
  }
}

Versioning

API Versions

Current version: v1

Specify version in URL:

https://api.yourapp.com/v1/workflows

Deprecation Policy

  • 12 months notice before deprecation
  • Migration guides provided
  • Sunset headers in responses

Next Steps

Tags

apidevelopmentreference