Quickstart

This guide will help you create and run your first workflow in under 5 minutes.

Prerequisites

An API key (see Authentication)
curl or any HTTP client

Step 1: Verify Your API Key

First, verify your API key is working by listing workflows:

curl http://localhost:3000/api/v1/workflows \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch('http://localhost:3000/api/v1/workflows', {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

interface WorkflowResponse {
  success: boolean;
  data: Workflow[];
}

const response = await fetch('http://localhost:3000/api/v1/workflows', {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
});
const data: WorkflowResponse = await response.json();
console.log(data);

You should see:

{
  "success": true,
  "data": []
}

Step 2: Create a Workflow

Create a simple workflow that transforms input data:

curl -X POST http://localhost:3000/api/v1/workflows \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Workflow",
    "description": "A simple echo workflow",
    "trigger": { "type": "api" },
    "steps": [{
      "id": "echo",
      "type": "transform",
      "name": "Echo Input",
      "config": {
        "mapping": {
          "message": "{{input.message}}",
          "timestamp": "{{now}}"
        }
      }
    }]
  }'

const workflow = {
  name: 'My First Workflow',
  description: 'A simple echo workflow',
  trigger: { type: 'api' },
  steps: [{
    id: 'echo',
    type: 'transform',
    name: 'Echo Input',
    config: {
      mapping: {
        message: '{{input.message}}',
        timestamp: '{{now}}'
      }
    }
  }]
};

const response = await fetch('http://localhost:3000/api/v1/workflows', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(workflow)
});

const data = await response.json();
console.log('Created workflow:', data.data.id);

interface CreateWorkflowRequest {
  name: string;
  description?: string;
  trigger: { type: 'api' | 'webhook' | 'schedule' };
  steps: Array<{
    id: string;
    type: string;
    name: string;
    config: Record<string, unknown>;
  }>;
}

const workflow: CreateWorkflowRequest = {
  name: 'My First Workflow',
  description: 'A simple echo workflow',
  trigger: { type: 'api' },
  steps: [{
    id: 'echo',
    type: 'transform',
    name: 'Echo Input',
    config: {
      mapping: {
        message: '{{input.message}}',
        timestamp: '{{now}}'
      }
    }
  }]
};

const response = await fetch('http://localhost:3000/api/v1/workflows', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(workflow)
});

const data = await response.json();
console.log('Created workflow:', data.data.id);

Response:

{
  "success": true,
  "data": {
    "id": "wf_abc123...",
    "name": "My First Workflow",
    "status": "draft",
    "version": 1,
    "trigger": { "type": "api" },
    "steps": [...],
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
}

Save the workflow id from the response - you'll need it for the next steps.

Step 3: Activate the Workflow

Workflows start in draft status and must be activated before they can run:

curl -X POST http://localhost:3000/api/v1/workflows/{WORKFLOW_ID}/activate \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  `http://localhost:3000/api/v1/workflows/${workflowId}/activate`,
  {
    method: 'POST',
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
);
const data = await response.json();
console.log('Workflow status:', data.data.status); // "active"

Response:

{
  "success": true,
  "data": {
    "id": "wf_abc123...",
    "status": "active"
  }
}

Step 4: Run the Workflow

Now trigger your workflow with some input data:

curl -X POST http://localhost:3000/api/v1/workflows/{WORKFLOW_ID}/run \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "message": "Hello, Workflows!"
    }
  }'

const response = await fetch(
  `http://localhost:3000/api/v1/workflows/${workflowId}/run`,
  {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      input: { message: 'Hello, Workflows!' }
    })
  }
);
const data = await response.json();
console.log('Run ID:', data.data.runId);

Response:

{
  "success": true,
  "data": {
    "runId": "run_xyz789...",
    "status": "pending",
    "workflowId": "wf_abc123...",
    "workflowVersion": 1
  }
}

Step 5: Check the Run Status

Check the status of your workflow run:

curl http://localhost:3000/api/v1/runs/{RUN_ID} \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  `http://localhost:3000/api/v1/runs/${runId}`,
  {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
);
const data = await response.json();
console.log('Status:', data.data.status);
console.log('Output:', data.data.output);

Response (completed):

{
  "success": true,
  "data": {
    "id": "run_xyz789...",
    "status": "completed",
    "output": {
      "message": "Hello, Workflows!",
      "timestamp": "2024-01-15T10:00:05.000Z"
    },
    "startedAt": "2024-01-15T10:00:00.000Z",
    "completedAt": "2024-01-15T10:00:05.000Z"
  }
}

What's Next?

You've successfully created and run your first workflow! Here's what to explore next:

Authentication

Learn about API keys and security

First Real Workflow

Build a workflow with integrations

Triggers

Explore webhook, schedule, and Slack triggers

Integrations

Connect Stripe, Salesforce, HubSpot, and more

Quickstart

Authentication

First Real Workflow

Triggers

Integrations

On this page