> ## Documentation Index > Fetch the complete documentation index at: https://docs.featherhq.com/llms.txt > Use this file to discover all available pages before exploring further. # Create workflow execution > Create a new agent workflow execution ## OpenAPI ````yaml post /api/v1/workflow/{workflowId}/execution openapi: 3.0.0 info: version: 1.0.0 title: Feather AI API servers: - url: https://prod.featherhq.com description: Production environment security: [] paths: /api/v1/workflow/{workflowId}/execution: post: tags: - Workflows summary: Create workflow execution description: Create a new agent workflow execution parameters: - schema: type: string format: uuid required: true name: workflowId in: path requestBody: required: true content: application/json: schema: type: object properties: customerLeadId: type: string description: Customer lead identifier primaryPhone: type: string pattern: ^\+1(\d{10}|\d{3}-\d{3}-\d{4})|^\+[1-9]\d{1,14}$ zipcode: type: string nullable: true pattern: ^\d{5}(-?\d{4})?$ state: type: string nullable: true forwardingPhoneNumber: type: string pattern: ^\+1(\d{10}|\d{3}-\d{3}-\d{4})|^\+[1-9]\d{1,14}$ variables: type: object additionalProperties: type: string description: Variables for the execution metadata: allOf: - type: object properties: firstName: type: string lastName: type: string - type: object additionalProperties: nullable: true description: Additional metadata for the execution priorityDate: type: string format: date-time description: >- Lead priority date (ISO 8601). Later/newer dates = higher priority. Defaults to creation time. example: '2025-01-15T00:00:00Z' startAt: type: string format: date-time description: >- Deferred execution start time (ISO 8601 with timezone). The first workflow step delay is applied after this time. example: '2025-01-15T15:30:00Z' attempt: type: integer minimum: 0 default: 0 description: >- Starting step index for the execution (0-indexed). Must be less than the total number of steps in the workflow. example: 0 required: - customerLeadId - primaryPhone responses: '201': description: Agent workflow execution created successfully content: application/json: schema: type: object properties: id: type: string format: uuid description: Execution ID workflowId: type: string format: uuid description: Workflow ID status: type: string enum: - CREATED - RUNNING - COMPLETED - FAILED - CANCELLED - PAUSED description: Execution status startedAt: type: string description: Execution start timestamp completedAt: type: string nullable: true description: Execution completion timestamp customerLeadId: type: string nullable: true description: Customer lead identifier primaryPhone: type: string nullable: true description: Primary phone number metadata: anyOf: - allOf: - type: object properties: firstName: type: string lastName: type: string - type: object additionalProperties: nullable: true - nullable: true description: Execution metadata variables: type: object additionalProperties: type: string description: Variables for the execution disposition: type: string nullable: true enum: - COULD_NOT_CONNECT - NO_ANSWER - LEFT_VOICEMAIL - VOICEMAIL_DETECTED - SILENCE_TIMEOUT - BAD_NUMBER - NOT_INTERESTED - WARM_TRANSFER - WARM_TRANSFER_FAILED - CALENDLY - DNC - ENDED - FRAUD - LINE_BUSY - TEXT_CONSENT - CALL_AGAIN description: Final execution disposition definition: type: object properties: steps: type: array items: type: object properties: id: type: string format: uuid type: type: string enum: - CALL - TEXT description: Type of workflow step order: type: integer minimum: 1 description: Order of execution (1-indexed) delayInSecs: type: integer minimum: 0 default: 0 description: Delay in seconds before executing this step finishOn: type: array items: type: string enum: - COULD_NOT_CONNECT - NO_ANSWER - LEFT_VOICEMAIL - VOICEMAIL_DETECTED - SILENCE_TIMEOUT - BAD_NUMBER - NOT_INTERESTED - WARM_TRANSFER - WARM_TRANSFER_FAILED - CALENDLY - DNC - ENDED - FRAUD - LINE_BUSY - TEXT_CONSENT - CALL_AGAIN default: [] description: Call end reasons that should finish the workflow agentId: type: string format: uuid description: Agent to use for this step leaveVoicemail: type: boolean default: false description: Whether to leave voicemail for call steps initialMessage: type: string maxLength: 1600 description: >- SMS message body for TEXT steps. Supports {{variableName}} interpolation. count: type: integer minimum: 1 default: 1 description: >- Number of times to repeat this step before moving to next required: - type - order - agentId minItems: 1 description: Workflow steps isInfinite: type: boolean default: false description: >- If true, workflow loops indefinitely using last step config when defined steps are exhausted required: - steps description: Workflow definition snapshot stepExecutions: type: array items: type: object properties: id: type: string format: uuid description: Step execution ID workflowExecutionId: type: string format: uuid description: Workflow execution ID status: type: string enum: - PENDING - IN_PROGRESS - COMPLETED - FAILED - SKIPPED - CANCELLED description: Step status type: type: string enum: - CALL - TEXT description: Step type order: type: integer description: Step order delayInSecs: type: integer description: Delay in seconds finishOn: type: array items: type: string enum: - COULD_NOT_CONNECT - NO_ANSWER - LEFT_VOICEMAIL - VOICEMAIL_DETECTED - SILENCE_TIMEOUT - BAD_NUMBER - NOT_INTERESTED - WARM_TRANSFER - WARM_TRANSFER_FAILED - CALENDLY - DNC - ENDED - FRAUD - LINE_BUSY - TEXT_CONSENT - CALL_AGAIN description: Workflow finish conditions startedAt: type: string nullable: true description: Step start timestamp completedAt: type: string nullable: true description: Step completion timestamp leaveVoicemail: type: boolean description: Whether to leave voicemail disposition: type: string nullable: true enum: - COULD_NOT_CONNECT - NO_ANSWER - LEFT_VOICEMAIL - VOICEMAIL_DETECTED - SILENCE_TIMEOUT - BAD_NUMBER - NOT_INTERESTED - WARM_TRANSFER - WARM_TRANSFER_FAILED - CALENDLY - DNC - ENDED - FRAUD - LINE_BUSY - TEXT_CONSENT - CALL_AGAIN description: Step disposition agentId: type: string format: uuid description: Agent ID agentCall: type: object nullable: true properties: id: type: string format: uuid status: type: string callStartedAt: type: string nullable: true callEndedAt: type: string nullable: true callDuration: type: integer callEndedReason: type: string nullable: true enum: - COULD_NOT_CONNECT - NO_ANSWER - LEFT_VOICEMAIL - VOICEMAIL_DETECTED - SILENCE_TIMEOUT - BAD_NUMBER - NOT_INTERESTED - WARM_TRANSFER - WARM_TRANSFER_FAILED - CALENDLY - DNC - ENDED - FRAUD - LINE_BUSY - TEXT_CONSENT - CALL_AGAIN recordingUrl: type: string nullable: true supervisorRecordingUrl: type: string nullable: true summary: type: string nullable: true required: - id - status - callStartedAt - callEndedAt - callDuration - callEndedReason - recordingUrl - supervisorRecordingUrl - summary description: Associated agent call details required: - id - workflowExecutionId - status - type - order - delayInSecs - finishOn - startedAt - completedAt - leaveVoicemail - disposition - agentId - agentCall description: Step executions createdAt: type: string description: Creation timestamp stepIndex: type: number description: Current step index being processed nextRunAt: type: string nullable: true description: Next scheduled run timestamp priorityDate: type: string nullable: true description: Lead priority date required: - id - workflowId - status - startedAt - completedAt - customerLeadId - primaryPhone - metadata - disposition - definition - stepExecutions - createdAt '400': description: Bad Request content: application/json: schema: type: object properties: status: type: integer default: 400 message: type: string default: Bad request code: type: string enum: - BAD_REQUEST default: BAD_REQUEST success: type: boolean enum: - false default: false '402': description: Insufficient credits content: application/json: schema: type: object properties: status: type: integer default: 402 message: type: string default: Insufficient credits code: type: string enum: - PAYMENT_REQUIRED default: PAYMENT_REQUIRED success: type: boolean enum: - false default: false '500': description: Internal server error content: application/json: schema: type: object properties: status: type: integer default: 500 message: type: string default: Internal server error code: type: string enum: - INTERNAL_SERVER_ERROR default: INTERNAL_SERVER_ERROR success: type: boolean enum: - false default: false security: - ApiKey: [] components: securitySchemes: ApiKey: type: apiKey in: header name: X-API-Key ````