> ## Documentation Index > Fetch the complete documentation index at: https://docs.heymilo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a workflow step's config > Partially update one workflow step's config without touching other steps or posting-level fields. ``step_id`` is the step's ``type`` or its 1-based ``order``. ## OpenAPI ````yaml https://api.heymilo.ai/openapi.json patch /api/v2/postings/{posting_id}/workflow/{step_id} openapi: 3.1.0 info: title: HeyMilo Public API description: >- External developer-facing API for HeyMilo. Create interviewers with agentic workflows, ingest candidates, retrieve interview results, and manage workspace resources. version: 2.0.0 servers: - url: https://api.heymilo.ai description: Production security: - ApiKeyAuth: [] tags: - name: Interviewers description: >- Create, read, update, and manage interviewers. An interviewer (posting) combines job details with an AI agent configuration and agentic workflow. - name: Candidates description: >- Ingest candidates into an interviewer's workflow (sync or async, single or bulk) and list candidates with their progress. - name: Interviews description: >- Retrieve full interview results (scorecard, transcript, resume evaluation) and manage per-interview metadata. - name: Webhooks description: >- Register, list, and manage webhook endpoints that receive real-time event notifications. - name: Voices description: Browse the workspace voice registry for AI interviewer voices. - name: Phone Numbers description: List provisioned phone numbers for SMS and voice agents. - name: Sender Emails description: Manage sender email addresses used for candidate communications. - name: Email Templates description: View email templates configured for candidate outreach. - name: Email Template Groups description: View grouped email template configurations. - name: Design Templates description: View design templates that control the candidate interview UI. - name: Design Template Groups description: View grouped design template configurations. - name: Interview Templates description: >- View interview templates, reusable agent configurations cloned from a blueprint posting (workflow, questions, criteria, agent settings). - name: Domains description: Manage custom domains for white-labelled interview URLs. - name: Questions description: >- Create, read, update, delete, and reorder questions and criteria for an interviewer's workflow. Covers all modalities: voice, sms, form, resume_eligibility, resume_scoring, and voice_tags. - name: Workspaces description: >- List the workspaces accessible to the authenticated caller. API-key callers receive a single entry; OAuth callers receive every workspace they are a member of. paths: /api/v2/postings/{posting_id}/workflow/{step_id}: patch: tags: - Interviewers summary: Update a workflow step's config description: >- Partially update one workflow step's config without touching other steps or posting-level fields. ``step_id`` is the step's ``type`` or its 1-based ``order``. operationId: updateInterviewerWorkflowStep parameters: - name: posting_id in: path required: true schema: type: string title: Posting Id - name: step_id in: path required: true schema: type: string title: Step Id - name: X-API-KEY in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key - name: Authorization in: header required: false schema: anyOf: - type: string - type: 'null' title: Authorization - name: X-Workspace-Id in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Workspace-Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateWorkflowStepRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SingleResponse_PostingResponse_' '401': description: Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' components: schemas: UpdateWorkflowStepRequest: properties: config: additionalProperties: true type: object title: Config description: >- Partial step config. Allowed keys depend on the step's agent type (see the matching step config in the create request). Nested objects are replaced as a whole. Unknown keys return 400. examples: - company_overview_delivery_mode: summarized_delivery instructions: Updated step-only instructions. type: object required: - config title: UpdateWorkflowStepRequest description: Partial update of a workflow step's config. SingleResponse_PostingResponse_: properties: data: $ref: '#/components/schemas/PostingResponse' meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta description: Optional metadata. Shape varies by endpoint. type: object required: - data title: SingleResponse[PostingResponse] APIErrorResponse: properties: error: $ref: '#/components/schemas/APIError' type: object required: - error title: APIErrorResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError PostingResponse: properties: object: type: string const: posting title: Object description: Object type identifier. default: posting id: type: string title: Id description: Unique posting identifier. examples: - 13D77095 company_id: type: string title: Company Id description: ID of the company that owns this posting. examples: - comp_abc123 title: type: string title: Title description: Job title displayed to candidates. examples: - Senior Software Engineer name: anyOf: - type: string - type: 'null' title: Name description: URL-friendly slug for the posting. examples: - senior-software-engineer description: type: string title: Description description: Full job description text. examples: - We are looking for a senior software engineer... language: anyOf: - type: string - type: 'null' title: Language description: BCP-47 language code. default: en examples: - en - es interviewer_name: anyOf: - type: string - type: 'null' title: Interviewer Name description: Display name of the AI interviewer. examples: - Sarah status: type: string title: Status description: 'Posting status: ''draft'', ''active'', ''expired'', ''archived''.' examples: - active finalized: type: boolean title: Finalized description: Whether the posting has been finalized/activated. examples: - true archived: type: boolean title: Archived description: Whether the posting is archived. examples: - false test_posting: type: boolean title: Test Posting description: Whether this is a test posting. examples: - false workflow: items: $ref: '#/components/schemas/WorkflowStep' type: array title: Workflow description: Ordered list of agentic workflow steps. urls: anyOf: - $ref: '#/components/schemas/PostingURLs' - type: 'null' description: All URLs associated with this posting. deadline: anyOf: - type: number - type: 'null' title: Deadline description: Unix timestamp deadline for the posting. examples: - 1775174400 redirect_url: anyOf: - type: string - type: 'null' title: Redirect Url description: URL candidates are redirected to after completing the interview. examples: - https://acme.com/thank-you scheduling_url: anyOf: - type: string - type: 'null' title: Scheduling Url description: Calendar scheduling URL for shortlisted candidates. examples: - https://cal.com/acme/interview max_retakes: anyOf: - type: integer - type: 'null' title: Max Retakes description: Maximum number of interview retakes allowed. examples: - 1 allow_sms_comms: anyOf: - type: boolean - type: 'null' title: Allow Sms Comms description: Whether SMS communications are enabled. default: false instructions: anyOf: - type: string - type: 'null' title: Instructions description: General instructions for the AI interviewer shared with agents. company_overview: anyOf: - type: string - type: 'null' title: Company Overview description: Overview of the company shared with agents. job_overview: anyOf: - type: string - type: 'null' title: Job Overview description: Overview of the job/role shared with agents. interview_process_overview: anyOf: - type: string - type: 'null' title: Interview Process Overview description: Overview of the interview process shared with agents. company_overview_delivery_mode: anyOf: - type: string - type: 'null' title: Company Overview Delivery Mode description: How the AI interviewer delivers the company overview. job_overview_delivery_mode: anyOf: - type: string - type: 'null' title: Job Overview Delivery Mode description: How the AI interviewer delivers the job overview. interview_process_overview_delivery_mode: anyOf: - type: string - type: 'null' title: Interview Process Overview Delivery Mode description: How the AI interviewer delivers the interview process overview. phone_number_id: anyOf: - type: string - type: 'null' title: Phone Number Id description: ID of the phone number used for outbound calls. sender_email_id: anyOf: - type: string - type: 'null' title: Sender Email Id description: ID of the sender email configuration. email_template_group_id: anyOf: - type: string - type: 'null' title: Email Template Group Id description: ID of the email template group. design_template_group_id: anyOf: - type: string - type: 'null' title: Design Template Group Id description: ID of the design template group. retake_cooldown_days: anyOf: - type: number - type: 'null' title: Retake Cooldown Days description: Cooldown period in days before a candidate can retake. email_report_to_candidate: anyOf: - type: boolean - type: 'null' title: Email Report To Candidate description: Whether to email the interview report to the candidate. default: false ats_metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Ats Metadata description: >- ATS integration metadata for postings derived from an ATS (Import-from-ATS flow or `createPosting` with an ATS-derived `interview_template_id`). Null for postings not connected to an ATS. Common fields: - `source` (string): how the posting was created, e.g. `job_sync`. - `ats_name` (string): identifier of the ATS, e.g. `workable`, `bullhorn`. - `ats_job_id` (string): ID of the ATS job that backs this posting. - `ats_job_posting_id` (string, optional): ATS-side job-posting ID when distinct from `ats_job_id`. - `integration_id` (string, optional): heymilo ATS integration ID. - `job_ids` (string[], optional): ATS job IDs included in the mapping config. - `pending_activation` (bool): `true` while the agent is in the intermediate stage created by `createPosting` / `clonePosting` for ATS-derived postings. Candidate ingestion does not begin until the caller transitions out of this stage by calling `POST /postings/{posting_id}/activate`, which finalizes the posting and attaches the ATS mapping in one step. - `mapping_activated_at`, `mapping_activated_by` (read-only): audit fields stamped when the ATS mapping was attached. - `mapping_deactivated_at`, `mapping_deactivated_by` (read-only): audit fields stamped when the ATS mapping was last paused. examples: - ats_job_id: WK-12345 ats_name: workable pending_activation: true source: job_sync - ats_job_id: WK-12345 ats_name: workable mapping_activated_at: '2026-05-21T15:00:00' mapping_activated_by: api_key:abcd1234 pending_activation: false source: job_sync metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: >- Set of key-value pairs for storing additional information. Up to 50 keys, each key max 40 chars, each value max 500 chars. examples: - external_id: ats_12345 source: workday created_at: anyOf: - type: number - type: 'null' title: Created At description: Unix timestamp when the posting was created. examples: - 1739612400 updated_at: anyOf: - type: number - type: 'null' title: Updated At description: Unix timestamp when the posting was last updated. examples: - 1739617200 type: object required: - id - company_id - title - description - status - finalized - archived - test_posting title: PostingResponse description: |- A job posting with its full agentic workflow configuration. A posting represents a complete hiring pipeline — it defines the job, the AI agents involved, and how candidates progress through each screening step. APIError: properties: type: type: string title: Type description: Error category examples: - invalid_request_error code: type: string title: Code description: Machine-readable error code examples: - validation_error message: type: string title: Message description: Human-readable summary examples: - The request body failed validation param: anyOf: - type: string - type: 'null' title: Param description: Top-level parameter that caused the error doc_url: anyOf: - type: string - type: 'null' title: Doc Url description: Link to relevant documentation errors: items: $ref: '#/components/schemas/APIErrorDetail' type: array title: Errors description: Detailed per-field validation errors type: object required: - type - code - message title: APIError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError WorkflowStep: properties: id: anyOf: - type: string - type: 'null' title: Id description: Unique identifier for this workflow step. examples: - agent_vi_001 type: type: string title: Type description: 'Agent type: ''web_interview'', ''conversational_sms'', ''resume'', ''form''.' examples: - web_interview order: type: integer title: Order description: Position in the workflow pipeline (1-based). examples: - 1 config: additionalProperties: true type: object title: Config description: >- Agent-specific configuration. Shape varies by type. See GET /api/v2/schemas/agents for details. type: object required: - type - order title: WorkflowStep description: A single step in a posting's agentic workflow. PostingURLs: properties: candidate_url: anyOf: - type: string - type: 'null' title: Candidate Url description: Candidate-facing interview URL. examples: - https://candidates.heymilo.io/acme/senior-engineer ingestion_url_key: anyOf: - type: string - type: 'null' title: Ingestion Url Key description: >- URL key for candidate ingestion. Use with POST /intake/v1/candidate/{key}. examples: - ibURejyPMSlw6de0OZUdoxyoXTgWO78ey2NUo96EOG1gY review_url: anyOf: - type: string - type: 'null' title: Review Url description: Admin dashboard review URL. examples: - https://admin.heymilo.ai/w/ABC123/lab2/POST_ID/1-details type: object title: PostingURLs description: All URLs associated with a posting. APIErrorDetail: properties: code: type: string title: Code description: Machine-readable error code examples: - invalid_param message: type: string title: Message description: Human-readable explanation examples: - title must be between 3 and 200 characters param: anyOf: - type: string - type: 'null' title: Param description: Parameter that caused the error examples: - title type: object required: - code - message title: APIErrorDetail securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: API key for authentication. Pass your key in the X-API-KEY header. ````