Elaichi Synthetic tools API

openapi: 3.2.0
info:
  title: Elaichi Synthetic tools API
  version: 0.1.0
  description: 'Control-plane HTTP API for Elaichi, the MCP control plane for SaaS teams. Authenticate with an organization API token (create one in the Elaichi app under Settings → API tokens) sent as a bearer token, plus the `X-Organization-Id` header on org-scoped routes; the MCP and OAuth endpoints use their own protocols. A few actions are deliberately not available to an API token and must be done by a person in the Elaichi app: managing API and SCIM tokens, creating an organization, approving an access request, deleting an organization, and changing the two-factor requirement. The operations concerned say so. Endpoints used only by the Elaichi app itself (sign-in, consent screens, browser redirects, inbound webhooks) are not documented.'
servers:
- url: https://api.elaichi.ai
  description: Production
tags:
- name: Synthetic tools
paths:
  /synthetic-tool:
    get:
      operationId: listSyntheticTools
      summary: List synthetic tools
      tags:
      - Synthetic tools
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - result
                - next_cursor
                - prev_cursor
                properties:
                  result:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  next_cursor:
                    type:
                    - string
                    - 'null'
                  prev_cursor:
                    type:
                    - string
                    - 'null'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Lists synthetic tools (`syn_…`): multi-step tools defined in Elaichi rather than derived from a connector. They are placed in a template or toolbox as an entry of `type: "synthetic"`. Each row carries `owner` (`{ id, name, email }`) alongside `owner_user_id`; read it rather than resolving the id against the paginated member directory. Each row also carries `broken_step_count`, the number of steps whose connection has been deleted (0 = none).'
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/CursorQuery'
      - name: q
        in: query
        required: false
        description: Case-insensitive substring match on the tool's name or description. LIKE wildcards are matched literally. Max 200 characters.
        schema:
          type: string
          maxLength: 200
    post:
      operationId: createSyntheticTool
      summary: Create a synthetic tool
      tags:
      - Synthetic tools
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Each step calls a connector tool; steps may reference earlier results. `input_schema` is the JSON Schema the model sees. Add it to a template or toolbox with an entry naming its `synthetic_tool_id`. The response annotates each step the way `GET /synthetic-tool/{id}` does (`connection_state`, `connection_name`).
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - steps
              properties:
                name:
                  type: string
                description:
                  type: string
                input_schema:
                  type: object
                  additionalProperties: true
                steps:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
                  description: 'Each step may set `requires_caller`: up to 20 `caller.…` paths its `args_template`, `for_each` or the tool''s `output_template` read as `caller.email`, `caller.attributes.<key>` and so on. Every path read must be declared (400 `caller_binding_undeclared`); a computed reference such as `$keys(caller)` is 400 `caller_reference_dynamic`. A run with no value for one refuses with 409 `caller_binding_unresolved` before any step runs.'
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
  /synthetic-tool/validate:
    post:
      operationId: validateSyntheticTool
      summary: Validate a synthetic tool draft without saving it
      tags:
      - Synthetic tools
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request body over 4 MiB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Same body shape as POST /synthetic-tool, checked as a new tool. Always 200 with every problem found, errors first -- `{ issues: (severity, step, field, message)[] }`, at most 50 -- including connection and restriction problems that POST answers with 404/403. Any error-severity issue means POST would reject it. Not checked: the name/description language check, a name already in use, and PATCH''s exemption for unchanged steps. Bodies over 4 MiB are 413.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - description
              - steps
              properties:
                name:
                  type: string
                description:
                  type: string
                input_schema:
                  type: object
                  additionalProperties: true
                steps:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
                  description: 'Each step may set `requires_caller`: up to 20 `caller.…` paths its `args_template`, `for_each` or the tool''s `output_template` read as `caller.email`, `caller.attributes.<key>` and so on. Every path read must be declared (400 `caller_binding_undeclared`); a computed reference such as `$keys(caller)` is 400 `caller_reference_dynamic`. A run with no value for one refuses with 409 `caller_binding_unresolved` before any step runs.'
                output_template:
                  type:
                  - string
                  - 'null'
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
  /synthetic-tool/{id}:
    get:
      operationId: getSyntheticTool
      summary: Get a synthetic tool
      tags:
      - Synthetic tools
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Each step carries read-only `connection_state`, computed on read: `ok` (the connection exists and the caller can see it; `connection_name` is its display name), `missing` (the connection was deleted; the step keeps its `connection_id` and cannot run until it is pointed at another connection) or `unavailable` (the connection exists but the caller cannot see it, so it is not named). A step with no `connection_id` has neither field. Request bodies never accept these; they are stripped if echoed back. `broken_step_count` (steps whose state is `missing`) rides along, as on the list.'
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Synthetic tool id (`syn_…`).
    patch:
      operationId: updateSyntheticTool
      summary: Update a synthetic tool
      tags:
      - Synthetic tools
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Updates a synthetic tool. Merge-patch at the top level, but **`steps` and `input_schema` are replaced wholesale when present**. Every template/toolbox entry referencing this tool picks the change up immediately. The response annotates each step with `connection_state` / `connection_name`, same as `GET /synthetic-tool/{id}`.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Synthetic tool id (`syn_…`).
    delete:
      operationId: deleteSyntheticTool
      summary: Delete a synthetic tool
      tags:
      - Synthetic tools
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Deletes a synthetic tool. Irreversible. Template/toolbox entries that reference it stop resolving to a tool.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Synthetic tool id (`syn_…`).
  /synthetic-tool/{id}/execute:
    post:
      operationId: executeSyntheticTool
      summary: Execute a synthetic tool
      tags:
      - Synthetic tools
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Runs the tool now, against live third-party systems, using the caller's connections — this is not a dry run. Arguments are validated against the tool's `input_schema`.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                arguments:
                  type: object
                  additionalProperties: true
                  description: Matching the tool's input schema.
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Synthetic tool id (`syn_…`).
components:
  schemas:
    Success:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
    Error:
      type: object
      required:
      - error
      description: The Elaichi error envelope. The MCP OAuth endpoints under `/oauth` are the exception — they return RFC 6749 errors instead (see `OAuthError`).
      properties:
        error:
          type: object
          required:
          - message
          - code
          properties:
            message:
              type: string
              description: Human-readable. 5xx messages are deliberately generic.
            code:
              type: string
              description: Stable machine-readable code, e.g. `not_found`, `subscription_required`.
            details:
              description: Structured detail for codes that carry one, e.g. `toolboxes_need_resolution`.
            feature:
              type: string
              description: The gated feature, on entitlement failures.
            plan:
              type:
              - string
              - 'null'
              enum:
              - personal
              - gold
              - black
              - null
          additionalProperties: true
  parameters:
    OrganizationIdHeader:
      name: X-Organization-Id
      in: header
      required: false
      description: Target organization (`org_…`). Required for cookie/session auth on org-scoped routes; optional for API tokens, which carry their organization, and rejected when it names a different one.
      schema:
        type: string
    CursorQuery:
      name: cursor
      in: query
      required: false
      description: Opaque cursor — pass the `next_cursor` from a previous response. Ignored by unpaginated endpoints.
      schema:
        type: string
    LimitQuery:
      name: limit
      in: query
      required: false
      description: Page size. Defaults to 50. Values above 200 are silently clamped to 200 rather than rejected; a value below 1, or a non-integer, is a 400. Ignored by the endpoints documented as unpaginated.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: session or API token
      description: '`Authorization: Bearer <token>` with an org-scoped API token (`elch_{org_id}_{64 hex}`), created in the Elaichi app under Settings → API tokens. The Elaichi app itself signs in with a session cookie, which is also accepted but is not meant for integrations. Two other credential families exist and are NOT interchangeable with this one: an MCP OAuth access token (`POST /mcp` only) and a SCIM token (`/scim/v2/*` only).'
    mcpOAuth:
      type: oauth2
      description: MCP OAuth access token, used only by `POST /mcp` — not interchangeable with `bearerAuth`. Discovered per RFC 9728/8414 at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`.
      flows:
        authorizationCode:
          authorizationUrl: https://api.elaichi.ai/oauth/authorize
          tokenUrl: https://api.elaichi.ai/oauth/token
          scopes:
            mcp:read: Anything you can already see in Elaichi. Never secret values. It can also ask an admin for access to something restricted for you.
            mcp:write: Create and change teams, roles, toolboxes, templates and connections, and share access.
            mcp:destructive: Permanently delete data and remove access in Elaichi. This cannot be undone.
            mcp:tools: Run tools from the toolboxes you choose next, deleting in your connected apps included. It can also ask an admin for access to something restricted for you.
            openid: That you are signed in, and the user ID we use for you. Nothing else.
            email: Your email address, and whether it is verified. Apps use this to check your domain.