> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engini.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Compile a plan

> Returns the compiled workflow and every diagnostic. Errors do not fail the call: a plan with errors still answers 200, and create or update would refuse it with 422.



## OpenAPI

````yaml /developers/api-reference/openapi.json post /v1/workflows/compile
openapi: 3.0.0
info:
  title: Engini API
  version: v1
  description: The Engini public API.
servers:
  - url: https://api.engini.io
security:
  - Bearer: []
  - ApiKey: []
tags:
  - name: Auth
    description: Identify the caller a Developer API request is authenticated as.
  - name: On-prem agents
    description: >-
      Provision and manage agents that run Engini tasks inside a customer's
      network.
  - name: Applications
    description: >-
      Discover the applications (toolkits) available in Engini and their
      connection requirements.
  - name: Tools
    description: Browse and execute the tools exposed by Engini applications.
  - name: Toolsets
    description: Manage toolsets - named groupings of connections and tools.
  - name: McpServers
    description: >-
      Inspect and maintain MCP servers - the account-wide endpoints that expose
      Engini tools and workflows over the Model Context Protocol. Distinct from
      the MCPClient connection kind, which is Engini consuming a third-party MCP
      server.
  - name: Connections
    description: >-
      Manage connections to applications, including OAuth sign-in and
      default-connection selection.
  - name: Folders
    description: >-
      List the folders that organize workflows in each workspace and
      environment.
  - name: Workflows
    description: >-
      List workflows, and build them from a plan: search the catalog, read
      schemas and options, compile, create and update.
  - name: Executions
    description: >-
      Read execution history for workflows, table automations and app business
      rules, including per-step logs and recorded payloads.
  - name: Triggers
    description: >-
      Create triggers that fire when something changes in a connected app, and
      manage the destinations their events are delivered to.
paths:
  /v1/workflows/compile:
    post:
      tags:
        - Workflows
      summary: Compile a plan
      description: >-
        Returns the compiled workflow and every diagnostic. Errors do not fail
        the call: a plan with errors still answers 200, and create or update
        would refuse it with 422.
      operationId: Workflows_Compile
      parameters: []
      requestBody:
        description: The plan, as JSON.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompileRequest'
        required: true
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompiledWorkflowDto'
        '400':
          description: >-
            Bad request - an invalid parameter or body, or SCOPE_REQUIRED for a
            write with a key that has no workspace (problem+json).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BuilderProblem'
        '401':
          description: Unauthorized - missing or invalid bearer token or API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Forbidden - API_KEY_REQUIRED for a Bearer token or an account-level
            key, PERMISSION_DENIED when the key's user may not create workflows
            here (problem+json); FORBIDDEN, GUEST_NOT_ALLOWED or
            SCOPE_UNRESOLVED when a gate in front of the builder refuses first
            (the ErrorResponse envelope, application/json).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BuilderProblem'
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            Not found - the workflow, app, table or connection is not visible to
            this key, or the key's user may not read here (problem+json).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BuilderProblem'
        '429':
          description: >-
            Too many requests - the account's limit (ErrorResponse body) or this
            key's per-operation limit (empty body). Both send Retry-After.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error (problem+json).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BuilderProblem'
        '502':
          description: >-
            Bad gateway - the connected system refused or failed the read
            (problem+json).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BuilderProblem'
      security:
        - Bearer: []
        - ApiKey: []
      x-codeSamples:
        - lang: python
          label: Python
          source: |-
            from engini import Engini

            client = Engini()  # reads ENGINI_API_KEY

            # dry run: nothing is written; check has_errors on the result
            result = client.workflows.compile(plan)
            print(result.has_errors)
        - lang: typescript
          label: TypeScript
          source: |-
            import { Engini } from "@engini/sdk";

            const client = new Engini(); // reads ENGINI_API_KEY

            // dry run: nothing is written; check hasErrors on the result
            const result = await client.workflows.compile({ plan });
            console.log(result.hasErrors);
        - lang: bash
          label: CLI
          source: engini workflows compile --file plan.json
components:
  schemas:
    CompileRequest:
      type: object
      description: >-
        POST compile's body. BaseWorkflowId names a saved workflow the plan
        edits: it is loaded

        server-side under the request's scope, never taken from the body.
      additionalProperties: false
      properties:
        plan:
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/WorkflowPlan'
        baseWorkflowId:
          type: integer
          format: int32
          nullable: true
    CompiledWorkflowDto:
      type: object
      description: >-
        What a compile produced, for display and repair. Null steps/jumps when
        the plan could not be laid out.
      additionalProperties: false
      required:
        - diagnostics
        - keyMap
        - workspaceId
        - environmentId
        - hasErrors
      properties:
        name:
          type: string
          nullable: true
        steps:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/CompiledStep'
        jumps:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/CompiledJump'
        diagnostics:
          type: array
          items:
            $ref: '#/components/schemas/BuilderDiagnostic'
        keyMap:
          type: object
          additionalProperties:
            type: integer
            format: int32
        workspaceId:
          type: string
          description: >-
            The workspace a create/update of this plan would land in: the
            request's resolved scope.
          format: uuid
        environmentId:
          type: string
          description: The environment a create/update of this plan would land in.
          format: uuid
        hasErrors:
          type: boolean
    BuilderProblem:
      type: object
      description: >-
        The builder's error body as it is sent (application/problem+json).
        Documentation only: the controller writes it

        from WorkflowBuilderApiError with the HTTP status added.
      additionalProperties: false
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: The HTTP status, repeated in the body.
          format: int32
        code:
          type: string
          description: >-
            A stable machine-readable code, such as PLAN_HAS_ERRORS or
            REVISION_CONFLICT.
        path:
          type: string
          description: The request member the refusal is about, when there is one.
          nullable: true
        message:
          type: string
          description: What failed, in plain words.
        fix:
          type: string
          description: What to do about it, when the builder knows.
          nullable: true
        diagnostics:
          type: array
          description: 'With PLAN_HAS_ERRORS: every diagnostic of the refused plan.'
          nullable: true
          items:
            $ref: '#/components/schemas/BuilderDiagnostic'
        currentRevisionId:
          type: integer
          description: 'With REVISION_CONFLICT: the workflow''s revision now.'
          format: int64
          nullable: true
    ErrorResponse:
      type: object
      description: >-
        Unified machine-readable error envelope returned by every non-200
        Developer API response.
      additionalProperties: false
      required:
        - errorCode
        - message
        - requestId
        - timestamp
      properties:
        errorCode:
          type: string
          description: Machine-readable error code identifying the failure.
        message:
          type: string
          description: Human-readable error message.
        requestId:
          type: string
          description: Identifier of the request, for support/correlation.
        timestamp:
          type: string
          description: Timestamp when the error occurred (ISO 8601).
        details:
          type: array
          description: Per-field validation details, when applicable.
          nullable: true
          items:
            $ref: '#/components/schemas/ErrorDetail'
    WorkflowPlan:
      type: object
      description: The plan an AI agent writes; the compiler turns it into a real workflow.
      additionalProperties: false
      required:
        - name
        - trigger
        - steps
      properties:
        name:
          type: string
        trigger:
          $ref: '#/components/schemas/PlanStep'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/PlanStep'
        notes:
          type: array
          description: >-
            Canvas sticky notes; see PlanNotes. Left out, the workflow keeps its
            notes; [] clears them; an

            array is the full set (a note with a stored id is overlaid on that
            note). Init-only, never a positional

            parameter, so the three new WorkflowPlan(...) sites stay as they
            are.
          nullable: true
          items:
            $ref: '#/components/schemas/PlanNote'
        table:
          type: string
          description: >-
            The table this workflow is an automation of (a Tables table id), for
            a Tables trigger (record created, updated or

            deleted). Left out on an update, the workflow keeps its table; a
            workflow's table is set when it is created and

            never changes (TableNotChangeable). Read through TableIdOf.
          nullable: true
    CompiledStep:
      type: object
      additionalProperties: false
      required:
        - stepNo
        - parentStepNo
        - connectionId
        - inputs
      properties:
        key:
          type: string
          description: >-
            The plan key of the step, or null for a step the plan has no key for
            (a container's branch).
          nullable: true
        stepNo:
          type: integer
          format: int32
        parentStepNo:
          type: integer
          format: int32
        activitySlug:
          type: string
          description: >-
            The plan's tool, block.{type} for a block, null for an opaque or
            branch step.
          nullable: true
        connectionId:
          type: integer
          format: int32
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/CompiledInput'
    CompiledJump:
      type: object
      additionalProperties: false
      required:
        - from
        - to
        - isFailedTarget
      properties:
        from:
          type: integer
          format: int32
        to:
          type: integer
          format: int32
        isFailedTarget:
          type: boolean
          description: The target runs on the failure of From.
    BuilderDiagnostic:
      type: object
      additionalProperties: false
      required:
        - severity
        - code
        - message
      properties:
        severity:
          type: string
        code:
          type: string
        stepKey:
          type: string
          nullable: true
        field:
          type: string
          nullable: true
        message:
          type: string
    ErrorDetail:
      type: object
      description: A single field-level error detail within an ErrorResponse.
      additionalProperties: false
      required:
        - field
        - issue
      properties:
        field:
          type: string
          description: Name of the field the issue relates to.
        issue:
          type: string
          description: Description of the issue with the field.
    PlanStep:
      type: object
      additionalProperties: false
      required:
        - key
        - type
        - connection
        - inputs
      properties:
        key:
          type: string
        type:
          type: string
          description: >-
            action|if|foreach|switch|do_while|scope|init_variable|set_variable|delay|stop|ai_agent|opaque
        tool:
          type: string
          description: Catalog slug, for action/trigger.
          nullable: true
        connection:
          type: string
          description: '"auto" | "none" | "<connectorId>"'
        inputs:
          type: object
          description: 'Never null: a JSON null is normalised to empty.'
          additionalProperties:
            type: string
        condition:
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/PlanCondition'
        then:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/PlanStep'
        else:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/PlanStep'
        items:
          type: string
          nullable: true
        do:
          type: array
          description: >-
            The body of a foreach, a do_while (run while its condition holds) or
            a scope.
          nullable: true
          items:
            $ref: '#/components/schemas/PlanStep'
        cases:
          type: array
          description: >-
            A switch's cases, first case first; the value compared is the step's
            inputs.data. Every case whose

            value equals it is tried in order and the last match runs, so give
            each case a distinct value.
          nullable: true
          items:
            $ref: '#/components/schemas/PlanCase'
        default:
          type: array
          description: >-
            A switch's default branch: runs when no case matches. Every switch
            has one, possibly empty.
          nullable: true
          items:
            $ref: '#/components/schemas/PlanStep'
        onFailure:
          type: array
          description: >-
            The step's failure path: a chain that runs when this step fails,
            beside it in the same container (not inside it).

            Its first step runs only on failure; the rest follow it. A plan can
            add a failure path and edit the steps on one,

            but never re-point or delete an existing one (that stays a designer
            action).
          nullable: true
          items:
            $ref: '#/components/schemas/PlanStep'
        ref:
          type: integer
          description: 'Opaque steps: the StepNo in the base workflow.'
          format: int32
          nullable: true
        schedule:
          description: >-
            The trigger's schedule, only on a schedule (polling) trigger; see
            PlanScheduleMapper. Left out, an

            existing trigger keeps the schedule it has.
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/PlanSchedule'
        listenColumns:
          type: array
          description: >-
            The trigger's "columns to listen to": only events that change one of
            them fire it, each column one provider

            subscription; see PlanTriggerGateMapper. Only on a trigger whose
            tool offers it. Left out, an existing

            trigger keeps the columns it has; [] removes them.
          nullable: true
          items:
            type: string
        filters:
          type: array
          description: >-
            A list tool's filters (the designer's filter rows, all of which must
            match): only on a tool that offers filters; see

            PlanQueryMapper. The step has exactly the filters, top and sorts the
            plan gives it: left out means none.
          nullable: true
          items:
            $ref: '#/components/schemas/PlanFilter'
        top:
          type: integer
          description: >-
            Return at most this many records (the designer's "Select top"); only
            on a tool that offers it.
          format: int32
          nullable: true
        sorts:
          type: array
          description: >-
            A list tool's sort order, first entry first; only on a tool that
            offers sorting.
          nullable: true
          items:
            $ref: '#/components/schemas/PlanSort'
        advancedFilter:
          type: boolean
          description: >-
            Sort & Filter only: each filter's field is an expression over the
            current record instead of a field name:

            the data reference followed by the field (data {{s2}}, field
            {{s2.Amount}}: a list action's array is the step itself).

            Left out means plain field-name filters.
          nullable: true
        offset:
          type: integer
          description: >-
            Sort & Filter only: skip this many records before the ones returned
            (the designer's "Offset").
          format: int32
          nullable: true
        sample:
          type: string
          description: >-
            A Parse JSON step's sample: a synthetic JSON (or XML) document of
            the shape the step's content will hold.

            Its output schema is generated from it, so {{key.field}} resolves.
            Stored in clear text with the workflow:

            never paste a real record. Left out on an existing step, the saved
            schema is kept.
          nullable: true
        mapDictionary:
          type: boolean
          description: >-
            A Parse JSON step: read JSON objects whose keys are ids (a
            dictionary) as an array of entries.
          nullable: true
        subItems:
          type: object
          description: >-
            A tool's sub-item tables (Http Request's Queries and Headers), by
            table name: one row

            ({field: value}) or a list of rows; see PlanSubItemMapper. Only on a
            tool that offers the

            table. Like filters, the step has exactly the tables the plan gives
            it: an offered table left out is cleared.
          nullable: true
          additionalProperties:
            type: array
            items:
              type: object
              additionalProperties:
                type: string
        model:
          description: >-
            An ai_agent step's LLM; see PlanAiAgentMapper. Left out on an
            existing agent, the agent keeps the

            model it has (it cannot run without one); required on a new agent.
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/PlanAiModel'
        memory:
          description: >-
            An ai_agent step's chat memory. Left out, the agent has none (an
            existing one is cleared).
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/PlanAiMemory'
        tools:
          type: array
          description: >-
            An ai_agent step's tools (connector actions the LLM may call), the
            full set. Left out, the agent has none (an

            existing set is cleared). Tools the plan cannot name (MCP,
            knowledge, worker, sub-agent) are never touched.
          nullable: true
          items:
            $ref: '#/components/schemas/PlanAiTool'
        value:
          description: >-
            An init_variable step's value as a JSON tree (TYPE object or array):
            the step is written in the

            designer's Manual mode, one typed property per leaf, so a
            {{key.path}} in a leaf resolves on its own; see

            PlanVariableValueMapper. Left out, VALUE is the raw text of
            inputs.VALUE (Raw mode).
          nullable: true
        valueTypes:
          type: object
          description: >-
            The designer type of a Value leaf, by JSON Pointer
            ("/customer/dueOn": "date"), where inference

            cannot tell it: a date (JSON has none), or a number or boolean
            written as a {{key.path}} reference.
          nullable: true
          additionalProperties:
            type: string
    PlanNote:
      type: object
      description: >-
        A canvas sticky note (CanvasNotesJson). Id is optional on write (the
        server

        mints one) and always present on read-back, so a later plan can address
        the note.
      additionalProperties: false
      properties:
        id:
          type: string
          nullable: true
        content:
          type: string
          nullable: true
        x:
          type: number
          format: double
          nullable: true
        'y':
          type: number
          format: double
          nullable: true
        width:
          type: number
          format: double
          nullable: true
        height:
          type: number
          format: double
          nullable: true
        color:
          type: string
          nullable: true
    CompiledInput:
      type: object
      additionalProperties: false
      required:
        - field
      properties:
        field:
          type: string
        value:
          type: string
          nullable: true
    PlanCondition:
      type: object
      description: 'Op: eq|ne|gt|gte|lt|lte|contains|empty|notempty'
      additionalProperties: false
      required:
        - left
        - op
        - right
      properties:
        left:
          type: string
        op:
          type: string
        right:
          type: string
    PlanCase:
      type: object
      description: >-
        One case of a switch: the value it matches (a literal or a reference)
        and the steps it runs.
      additionalProperties: false
      properties:
        value:
          type: string
          nullable: true
        steps:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/PlanStep'
    PlanSchedule:
      type: object
      description: >-
        A polling (schedule) trigger's schedule (the built-in Schedule trigger,
        or an app trigger that checks on a timer such as

        Gmail or Outlook "Check for new emails"), in the words of the designer's
        schedule editor. Times are UTC (the designer's

        "Starting (UTC)") unless TimeZone names the zone they are written in.
      additionalProperties: false
      properties:
        frequency:
          type: string
          description: minute|hour|day|week|month
          nullable: true
        interval:
          type: integer
          description: Run every interval units of Frequency.
          format: int32
          nullable: true
        startDate:
          type: string
          description: yyyy-MM-dd; today (UTC) when left out.
          nullable: true
        startTime:
          type: string
          description: HH:mm; 00:00 when left out.
          nullable: true
        weekDays:
          type: string
          description: >-
            Days of the week, 0 = Sunday … 6 = Saturday: "1,2,3,4,5" or
            [1,2,3,4,5]. Every day when left out. Only a weekly schedule

            reads them, so a subset with any other frequency is refused.
          nullable: true
        timeZone:
          type: string
          description: >-
            The IANA zone StartDate/StartTime/time frames are written in; UTC
            when left out. A monthly

            schedule whose start lands on another day in UTC is refused (it
            repeats on its UTC day of the month).
          nullable: true
        timeFrames:
          type: array
          description: Daily windows to repeat in, every EveryMinutes minutes.
          nullable: true
          items:
            $ref: '#/components/schemas/PlanTimeFrame'
    PlanFilter:
      type: object
      additionalProperties: false
      properties:
        field:
          type: string
          description: A filterable field of the tool's object.
          nullable: true
        operator:
          type: string
          description: >-
            eq|ne|gt|gte|lt|lte|contains|notcontains|startswith|endswith|notstartswith|notendswith|empty|notempty|in|notin
          nullable: true
        value:
          type: string
          description: Text, {{key.path}} references allowed; ignored by empty / notempty.
          nullable: true
    PlanSort:
      type: object
      additionalProperties: false
      properties:
        field:
          type: string
          description: A sortable field of the tool's object.
          nullable: true
        direction:
          type: string
          description: asc (the default) | desc
          nullable: true
    PlanAiModel:
      type: object
      additionalProperties: false
      properties:
        provider:
          type: string
          description: >-
            openai|anthropic|gemini|azure_openai|monday: the vendor whose chat
            model row the agent uses.
          nullable: true
        connection:
          type: string
          description: >-
            The vendor connection: auto or a connection id (never none: the
            agent needs one).
          nullable: true
        inputs:
          type: object
          description: The model row's inputs (model, temperature, ...), as written.
          nullable: true
          additionalProperties:
            type: string
    PlanAiMemory:
      type: object
      additionalProperties: false
      properties:
        sessionId:
          type: string
          description: 'The chat session the memory is kept under: text, references allowed.'
          nullable: true
        windowLength:
          type: string
          description: >-
            How many past messages the LLM sees (0-100); text, so a reference
            can be said.
          nullable: true
    PlanAiTool:
      type: object
      description: 'One tool of an AI agent: a connector action the LLM may call.'
      additionalProperties: false
      required:
        - connection
        - inputs
        - aiInputs
      properties:
        name:
          type: string
          description: >-
            The name the LLM calls the tool by: [a-z0-9_], 1-128, unique within
            the agent. Not a plan key.
          nullable: true
        tool:
          type: string
          description: The action's catalog slug.
          nullable: true
        connection:
          type: string
          description: '"auto" | "none" | "<connectorId>"'
        description:
          type: string
          description: >-
            What the LLM is told the tool does; left out, the action's own
            description is used.
          nullable: true
        inputs:
          type: object
          description: >-
            Fixed values, as a step's inputs; the LLM cannot change them. Never
            null.
          additionalProperties:
            type: string
        aiInputs:
          type: object
          description: >-
            Inputs the LLM fills at run time, by name, each with what the LLM is
            told it holds ("" for none). Never null.
          additionalProperties:
            type: string
    PlanTimeFrame:
      type: object
      additionalProperties: false
      properties:
        start:
          type: string
          description: HH:mm
          nullable: true
        end:
          type: string
          description: HH:mm, after Start.
          nullable: true
        everyMinutes:
          type: integer
          description: Always minutes, whatever the schedule's frequency.
          format: int32
          nullable: true
  securitySchemes:
    Bearer:
      type: http
      description: Enter your JWT token
      scheme: bearer
      bearerFormat: JWT
    ApiKey:
      type: apiKey
      description: >-
        Opaque Developer API key (prefix `eng_`). Authenticates as the key's
        owner and resolves the account automatically.
      name: x-api-key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.