> ## Documentation Index > Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt > Use this file to discover all available pages before exploring further. # Start workflow execution > Start a new execution of a workflow asynchronously. The workflow will begin processing in the background. You'll receive a 202 Accepted response with a tracking_id immediately. Use this tracking_id to: - Poll GET /workflow_executions with tracking_id filter to check status - Correlate execution events with your own systems The execution will fail if: - The workflow is not in 'active' status - Required phone_number is missing or invalid - The workflow definition is malformed Use cases: - Start workflow from external trigger (API, webhook, scheduled job) - Test workflow with specific initial variables - Retry failed execution with same parameters **Burst rate limit**: This endpoint has an additional per-workflow burst limiter on top of the general platform API rate limits. The burst counter is scoped by API key and workflow ID and resets every second. - `legacy` / `free`: 5 requests per second - `pro`: 15 requests per second - `enterprise` / `platform`: 30 requests per second Successful responses include `X-Burst-RateLimit-Limit` and `X-Burst-RateLimit-Remaining` headers. If the burst limit is exceeded, the API returns `429 Too Many Requests` with `Retry-After: 1`. ## OpenAPI ````yaml /api/platform/v1/openapi-workflows.yaml post /workflows/{workflow_id}/executions openapi: 3.1.0 info: title: Kapso Platform API – Advanced Resources version: 0.1.0 description: > Build WhatsApp automation workflows and serverless functions. Create multi-step conversation flows, inspect executions, and deploy custom logic. servers: - url: https://api.kapso.ai/platform/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Workflows description: Create and manage conversation workflows and executions - name: Workflow Triggers description: Configure workflow triggers to automate execution - name: Functions description: Manage serverless functions, deployments, and secrets - name: WhatsApp Conversations description: Query WhatsApp conversation data and related resources paths: /workflows/{workflow_id}/executions: parameters: - name: workflow_id in: path required: true schema: type: string format: uuid description: Workflow identifier post: tags: - Workflows summary: Start workflow execution description: > Start a new execution of a workflow asynchronously. The workflow will begin processing in the background. You'll receive a 202 Accepted response with a tracking_id immediately. Use this tracking_id to: - Poll GET /workflow_executions with tracking_id filter to check status - Correlate execution events with your own systems The execution will fail if: - The workflow is not in 'active' status - Required phone_number is missing or invalid - The workflow definition is malformed Use cases: - Start workflow from external trigger (API, webhook, scheduled job) - Test workflow with specific initial variables - Retry failed execution with same parameters **Burst rate limit**: This endpoint has an additional per-workflow burst limiter on top of the general platform API rate limits. The burst counter is scoped by API key and workflow ID and resets every second. - `legacy` / `free`: 5 requests per second - `pro`: 15 requests per second - `enterprise` / `platform`: 30 requests per second Successful responses include `X-Burst-RateLimit-Limit` and `X-Burst-RateLimit-Remaining` headers. If the burst limit is exceeded, the API returns `429 Too Many Requests` with `Retry-After: 1`. operationId: createWorkflowExecution requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkflowExecutionCreateRequest' responses: '202': description: Workflow execution queued successfully (processing in background) headers: X-Burst-RateLimit-Limit: schema: type: integer description: >- Maximum workflow execution requests allowed per second for this workflow and API key X-Burst-RateLimit-Remaining: schema: type: integer description: >- Remaining workflow execution requests in the current one-second window for this workflow and API key content: application/json: schema: $ref: '#/components/schemas/WorkflowExecutionCreateAcceptedResponse' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '422': $ref: '#/components/responses/ValidationError' '429': description: Workflow execution burst rate limit exceeded headers: X-Burst-RateLimit-Limit: schema: type: integer description: >- Maximum workflow execution requests allowed per second for this workflow and API key X-Burst-RateLimit-Remaining: schema: type: integer description: >- Remaining workflow execution requests in the current one-second window for this workflow and API key Retry-After: schema: type: integer description: Seconds to wait before retrying. This burst limiter returns `1`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Burst rate limit exceeded message: >- Too many workflow execution requests in a short period. Try again in 1 second. components: schemas: WorkflowExecutionCreateRequest: type: object required: - workflow_execution properties: workflow_execution: type: object required: - phone_number properties: phone_number: type: string description: > E.164 formatted phone number for the conversation participant (e.g., '+14155552671'). This number will be normalized and used for conversation routing. example: '+14155552671' phone_number_id: type: string description: > WhatsApp phone number identifier to use for sending messages. Use this to specify which WhatsApp Business number should handle the conversation. Preferred over whatsapp_config_id. whatsapp_config_id: type: integer deprecated: true description: > [DEPRECATED] Internal WhatsApp configuration ID. Use phone_number_id instead. This field is maintained for backward compatibility but may be removed in future versions. variables: type: object description: > Initial user-defined variables available to the workflow (key-value pairs). These variables can be accessed and modified throughout workflow execution using variable syntax (e.g., {{user.name}}). additionalProperties: true example: user_name: Alice order_id: ORD-12345 priority: high context: type: object description: > Additional contextual data passed to the workflow but not treated as user variables. Use this for metadata or system-specific information that shouldn't be part of the variable namespace. additionalProperties: true example: source: mobile_app campaign_id: SUMMER2024 initial_data: type: object description: > Custom payload passed to the workflow's first step. Structure depends on the workflow's initial node configuration. Use this for complex initialization data. additionalProperties: true description: > Request to start a new workflow execution. Executions are processed asynchronously - you'll receive a tracking_id immediately and can poll for results using GET /workflow_executions/{id}. WorkflowExecutionCreateAcceptedResponse: type: object required: - data properties: data: $ref: '#/components/schemas/WorkflowExecutionCreateAccepted' description: Async workflow execution initiation response (HTTP 202) ErrorResponse: type: object required: - error properties: error: type: string description: Human-readable error message WorkflowExecutionCreateAccepted: type: object required: - message - workflow_id - id - tracking_id properties: message: type: string description: Confirmation message example: Workflow execution initiated workflow_id: type: string format: uuid description: ID of the workflow being executed id: type: string format: uuid description: > Unique execution identifier. Use this to retrieve execution details via GET /workflow_executions/{id} or to resume waiting executions via POST /workflow_executions/{id}/resume. tracking_id: type: string format: uuid description: > Unique identifier for tracking this execution. Use this to query execution status via GET /workflow_executions (filter by tracking_id) or to correlate execution events with external systems. description: > Async response returned when workflow execution is successfully queued (HTTP 202 Accepted). The execution will begin processing in the background. Use the id to retrieve execution details or the tracking_id to monitor progress. responses: UnauthorizedError: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFoundError: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ValidationError: description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key ````