Workflows

Welcome to the Workflows documentation. This section provides detailed information about creating and using workflows.

Overview

Workflows are declarative state machines that orchestrate multiple functions to accomplish complex tasks. They allow you to define, execute, and iterate on business processes as clean and simple code.

Business-as-Code

We believe that you can define, execute, and iterate on business processes as clean & simple code. It should be simple enough for a non-technical business person to read and work with an AI or technical teammate to build and iterate on workflows.


import { AI } from 'workflows.do'
 
export default AI({
  onUserSignup: async ({ ai, api, db, event }) => {
    const { name, email, company } = event
 
    // Enrich content details with lookup from external data sources
    const enrichedContact = await api.apollo.search({ name, email, company })
    const socialProfiles = await api.peopleDataLabs.findSocialProfiles({ name, email, company })
    const githubProfile = socialProfiles.github ? await api.github.profile({ name, email, company, profile: socialProfiles.github }) : undefined
 
    // Using the enriched contact details, do deep research on the company and personal background
    const companyProfile = await ai.researchCompany({ company })
    const personalProfile = await ai.researchPersonalBackground({ name, email, enrichedContact })
    const socialActivity = await ai.researchSocialActivity({ name, email, enrichedContact, socialProfiles })
    const githubActivity = githubProfile ? await ai.summarizeGithubActivity({ name, email, enrichedContact, githubProfile }) : undefined
 
    // Schedule a highly personalized sequence of emails to optimize onboarding and activation
    const emailSequence = await ai.personalizeEmailSequence({ name, email, company, personalProfile, socialActivity, companyProfile, githubActivity })
    await api.scheduleEmails({ emailSequence })
 
    // Summarize everything, save to the database, and post to Slack
    const details = { enrichedContact, socialProfiles, githubProfile, companyProfile, personalProfile, socialActivity, githubActivity, emailSequence }
    const summary = await ai.summarizeContent({ length: '3 sentences', name, email, company, ...details })
    const { url } = await db.users.create({ name, email, company, summary, ...details })
    await api.slack.postMessage({ channel: '#signups', content: { name, email, company, summary, url } })
  },
})

Endpoints

List Workflows


GET /workflows

Returns a list of all workflows accessible to the authenticated user.

Query Parameters

Parameter	Type	Description
limit	integer	Maximum number of workflows to return (default: 20)
offset	integer	Number of workflows to skip (default: 0)
sort	string	Field to sort by (default: ‘createdAt’)
order	string	Sort order (‘asc’ or ‘desc’, default: ‘desc’)

Response


{
  "data": [
    {
      "id": "workflow_123",
      "name": "Customer Onboarding",
      "description": "Workflow for onboarding new customers",
      "createdAt": "2023-01-01T00:00:00Z",
      "updatedAt": "2023-01-02T00:00:00Z"
    }
    // ...
  ],
  "meta": {
    "total": 100,
    "limit": 20,
    "offset": 0
  }
}

Get Workflow


GET /workflows/:id

Returns details for a specific workflow.

Response


{
  "id": "workflow_123",
  "name": "Customer Onboarding",
  "description": "Workflow for onboarding new customers",
  "states": {
    "initial": {
      "type": "task",
      "task": "validateCustomerData",
      "next": "createAccount"
    },
    "createAccount": {
      "type": "task",
      "task": "createCustomerAccount",
      "next": "sendWelcomeEmail"
    },
    "sendWelcomeEmail": {
      "type": "task",
      "task": "sendEmail",
      "next": "complete"
    },
    "complete": {
      "type": "succeed"
    }
  },
  "functions": ["validateCustomerData", "createCustomerAccount", "sendEmail"],
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-02T00:00:00Z"
}

Create Workflow


POST /workflows

Creates a new workflow.

Request Body


{
  "name": "Customer Onboarding",
  "description": "Workflow for onboarding new customers",
  "states": {
    "initial": {
      "type": "task",
      "task": "validateCustomerData",
      "next": "createAccount"
    },
    "createAccount": {
      "type": "task",
      "task": "createCustomerAccount",
      "next": "sendWelcomeEmail"
    },
    "sendWelcomeEmail": {
      "type": "task",
      "task": "sendEmail",
      "next": "complete"
    },
    "complete": {
      "type": "succeed"
    }
  },
  "functions": ["validateCustomerData", "createCustomerAccount", "sendEmail"]
}

Response


{
  "id": "workflow_123",
  "name": "Customer Onboarding",
  "description": "Workflow for onboarding new customers",
  "states": {
    "initial": {
      "type": "task",
      "task": "validateCustomerData",
      "next": "createAccount"
    },
    "createAccount": {
      "type": "task",
      "task": "createCustomerAccount",
      "next": "sendWelcomeEmail"
    },
    "sendWelcomeEmail": {
      "type": "task",
      "task": "sendEmail",
      "next": "complete"
    },
    "complete": {
      "type": "succeed"
    }
  },
  "functions": ["validateCustomerData", "createCustomerAccount", "sendEmail"],
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-01T00:00:00Z"
}

Update Workflow


PUT /workflows/:id

Updates an existing workflow.

Request Body


{
  "name": "Enhanced Customer Onboarding",
  "description": "Improved workflow for onboarding new customers",
  "states": {
    "initial": {
      "type": "task",
      "task": "validateCustomerData",
      "next": "createAccount"
    },
    "createAccount": {
      "type": "task",
      "task": "createCustomerAccount",
      "next": "assignAccountManager"
    },
    "assignAccountManager": {
      "type": "task",
      "task": "assignManager",
      "next": "sendWelcomeEmail"
    },
    "sendWelcomeEmail": {
      "type": "task",
      "task": "sendEmail",
      "next": "scheduleFollowUp"
    },
    "scheduleFollowUp": {
      "type": "task",
      "task": "scheduleCall",
      "next": "complete"
    },
    "complete": {
      "type": "succeed"
    }
  },
  "functions": ["validateCustomerData", "createCustomerAccount", "assignManager", "sendEmail", "scheduleCall"]
}

Response


{
  "id": "workflow_123",
  "name": "Enhanced Customer Onboarding",
  "description": "Improved workflow for onboarding new customers",
  "states": {
    "initial": {
      "type": "task",
      "task": "validateCustomerData",
      "next": "createAccount"
    },
    "createAccount": {
      "type": "task",
      "task": "createCustomerAccount",
      "next": "assignAccountManager"
    },
    "assignAccountManager": {
      "type": "task",
      "task": "assignManager",
      "next": "sendWelcomeEmail"
    },
    "sendWelcomeEmail": {
      "type": "task",
      "task": "sendEmail",
      "next": "scheduleFollowUp"
    },
    "scheduleFollowUp": {
      "type": "task",
      "task": "scheduleCall",
      "next": "complete"
    },
    "complete": {
      "type": "succeed"
    }
  },
  "functions": ["validateCustomerData", "createCustomerAccount", "assignManager", "sendEmail", "scheduleCall"],
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-02T00:00:00Z"
}

Delete Workflow


DELETE /workflows/:id

Deletes a workflow.

Response


{
  "success": true,
  "message": "Workflow deleted successfully"
}

Execute Workflow


POST /workflows/:id/execute

Executes a workflow with the provided input.

Request Body


{
  "input": {
    "customer": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "company": "Acme Inc."
    }
  }
}

Response


{
  "id": "execution_123",
  "workflowId": "workflow_123",
  "status": "running",
  "input": {
    "customer": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "company": "Acme Inc."
    }
  },
  "currentState": "initial",
  "createdAt": "2023-01-01T00:00:00Z"
}

Get Workflow Execution


GET /workflows/executions/:id

Returns details for a specific workflow execution.

Response


{
  "id": "execution_123",
  "workflowId": "workflow_123",
  "status": "completed",
  "input": {
    "customer": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "company": "Acme Inc."
    }
  },
  "output": {
    "accountId": "account_456",
    "welcomeEmailSent": true
  },
  "stateHistory": [
    {
      "state": "initial",
      "enteredAt": "2023-01-01T00:00:00Z",
      "exitedAt": "2023-01-01T00:00:01Z",
      "output": {
        "valid": true
      }
    },
    {
      "state": "createAccount",
      "enteredAt": "2023-01-01T00:00:01Z",
      "exitedAt": "2023-01-01T00:00:02Z",
      "output": {
        "accountId": "account_456"
      }
    },
    {
      "state": "sendWelcomeEmail",
      "enteredAt": "2023-01-01T00:00:02Z",
      "exitedAt": "2023-01-01T00:00:03Z",
      "output": {
        "emailSent": true,
        "emailId": "email_789"
      }
    },
    {
      "state": "complete",
      "enteredAt": "2023-01-01T00:00:03Z",
      "exitedAt": null
    }
  ],
  "createdAt": "2023-01-01T00:00:00Z",
  "completedAt": "2023-01-01T00:00:03Z"
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests. For more information about error codes and how to handle errors, see the Error Handling documentation.

Rate Limiting

API requests are subject to rate limiting to ensure fair usage and system stability. For more information about rate limits and how to handle rate-limiting responses, see the Rate Limiting documentation.

Webhooks

You can configure webhooks to receive notifications about workflow events. For more information about webhooks, see the Webhooks documentation.

SDKs

We provide SDKs for popular programming languages to make it easier to integrate with the Workflows API: