openapi: 3.2.0
info:
  title: MindCloud Public Environments API
  version: 2.0.0
  description: REST surface under /v2. Authenticate with a company-scoped API key sent as a bearer token. Each key holds a set of permissions; each operation lists the ones it requires as the apiKey security roles. A request may use a permission only while the user who created the key also holds it.
servers:
- url: https://connect.mindcloud.co
security:
- apiKey: []
tags:
- name: Environments
paths:
  /v2/environments:
    get:
      operationId: v2-list-environments
      summary: List company environments with the number of scheduled workflows targeting each
      description: 'List company environments with the number of scheduled workflows targeting each. Use environment ids to filter runs.


        Each filterable field is also a query parameter: `status=active` matches it exactly, and bracket operators (eq, ne, gt, gte, lt, lte, contains, starts, ends, in, nin) compare, e.g. `createdOn[gte]=2026-01-01` or `status[in]=failed,cancelled`. contains, starts, and ends apply to text fields only.


        Requires the API key permission company:view.'
      tags:
      - Environments
      security:
      - apiKey:
        - company:view
      parameters:
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated fields to return; all of them when left out, and id always. Each item then carries only those keys, whatever its schema requires. Fields: id, name, isDefault, workflowCount, createdOn.'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - name: sort
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated sort fields; prefix one with - for descending. Sortable fields: id, name, isDefault, workflowCount, createdOn. Default: -isDefault,name,id.'
      - name: where
        in: query
        required: false
        schema:
          type: string
          maxLength: 2048
        description: 'RSQL filter expression. Filterable fields: id, name, isDefault, workflowCount, createdOn. Operators: ==, !=, >, >=, <, <=, =in=, =out=, =like=. Logical: ; (AND), , (OR); AND binds tighter than OR. Example: "status==active;name=like=Sales*"'
      - name: id
        in: query
        required: false
        schema:
          type: string
        description: 'Filter on id: `id=value` matches it exactly. Bracket operators: `id[ne]`, `id[gt]`, `id[gte]`, `id[lt]`, `id[lte]`, `id[contains]`, `id[starts]`, `id[ends]`, and `id[in]` / `id[nin]` with comma-separated values.'
      - name: name
        in: query
        required: false
        schema:
          type: string
        description: 'Filter on name: `name=value` matches it exactly. Bracket operators: `name[ne]`, `name[gt]`, `name[gte]`, `name[lt]`, `name[lte]`, `name[contains]`, `name[starts]`, `name[ends]`, and `name[in]` / `name[nin]` with comma-separated values.'
      - name: isDefault
        in: query
        required: false
        schema:
          type: boolean
        description: 'Filter on isDefault: `isDefault=value` matches it exactly. Bracket operators: `isDefault[ne]`, `isDefault[gt]`, `isDefault[gte]`, `isDefault[lt]`, `isDefault[lte]`, and `isDefault[in]` / `isDefault[nin]` with comma-separated values.'
      - name: workflowCount
        in: query
        required: false
        schema:
          type: integer
        description: 'Filter on workflowCount: `workflowCount=value` matches it exactly. Bracket operators: `workflowCount[ne]`, `workflowCount[gt]`, `workflowCount[gte]`, `workflowCount[lt]`, `workflowCount[lte]`, and `workflowCount[in]` / `workflowCount[nin]` with comma-separated values.'
      - name: createdOn
        in: query
        required: false
        schema:
          type: string
        description: 'Filter on createdOn: `createdOn=value` matches it exactly. A date or timestamp, such as 2026-10-01 or 2026-10-01T12:00:00Z. Bracket operators: `createdOn[ne]`, `createdOn[gt]`, `createdOn[gte]`, `createdOn[lt]`, `createdOn[lte]`, and `createdOn[in]` / `createdOn[nin]` with comma-separated values.'
      - $ref: '#/components/parameters/CompanyId'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Environment'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
                required:
                - success
                - data
                - meta
        default:
          description: Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
      description: Number of results to skip for pagination (default 0).
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100
      description: Maximum number of results to return (1-1000, default 100).
    CompanyId:
      name: X-Company-Id
      in: header
      required: false
      schema:
        type: string
      example: K3vX9qLm2RtA
      description: Optional. The id of a child organization of your API key's company to act on. Leave it out to act on the key's own company. See [Child organizations](https://mindcloud.co/docs/api/rest/introduction/child-organizations).
  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          properties:
            code:
              type: string
              description: 'Fixed by the status: 400 VALIDATION_FAILED, 401 UNAUTHORIZED, 403 FORBIDDEN, 404 NOT_FOUND, 409 CONFLICT, 410 GONE, 413 PAYLOAD_TOO_LARGE, 421 and 503 UNAVAILABLE, 429 RATE_LIMITED, 500 INTERNAL_ERROR, 502 PROVIDER_ERROR.'
              examples:
              - VALIDATION_FAILED
              - UNAUTHORIZED
              - FORBIDDEN
              - NOT_FOUND
              - CONFLICT
              - GONE
              - PAYLOAD_TOO_LARGE
              - RATE_LIMITED
              - INTERNAL_ERROR
              - PROVIDER_ERROR
              - UNAVAILABLE
            message:
              type: string
            details:
              type: object
              description: The specific cause (reason) and any evidence for it. Absent when the code says everything.
              properties:
                reason:
                  type: string
                  description: The specific cause, for example UNKNOWN_FILTER_FIELD or CONNECTION_IN_USE.
                field:
                  type: string
                  description: The parameter, filter, sort, or body field a 400 refused.
                accepted:
                  type: array
                  items: {}
                  description: 'What a 400 would have accepted instead: parameter names, field names, or enum values.'
                provider:
                  type: object
                  description: 'On 502 PROVIDER_ERROR: the provider answer that failed.'
                  properties:
                    status:
                      type: integer
                      description: The provider's HTTP status.
                    code:
                      type: string
                      description: The provider's own error code, when it sends one.
          required:
          - code
          - message
      required:
      - success
      - error
    ListMeta:
      type: object
      properties:
        pagination:
          type: object
          properties:
            totalCount:
              type: integer
              description: Matching records. A list read in SQL stops counting at 10000.
            totalCountExact:
              type: boolean
              description: False when totalCount stopped at that cap.
            hasNextPage:
              type: boolean
              description: True when another page follows. Page with this, not totalCount.
            hasPreviousPage:
              type: boolean
          required:
          - totalCount
          - totalCountExact
          - hasNextPage
          - hasPreviousPage
      required:
      - pagination
    Environment:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique id of the environment. Use it to filter runs.
        name:
          type:
          - string
          - 'null'
          description: The environment's name, like Production or Sandbox.
        isDefault:
          type:
          - boolean
          - 'null'
          description: True for the default environment.
        workflowCount:
          type:
          - integer
          - 'null'
          description: How many scheduled workflows target it.
        createdOn:
          type:
          - string
          - 'null'
          format: date-time
          description: When the environment was created.
      required:
      - id
      - name
      - isDefault
      - workflowCount
      - createdOn
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'Company-scoped MindCloud API key sent as `Authorization: Bearer <key>`. Each key holds permissions from the MindCloud roles catalog (workflow:view, workflow:run, universal:read, api_key:manage, ...), chosen when it is created; each operation lists the ones it requires as this scheme''s roles. A request may use a permission only while the user who created the key still holds it in the company the request acts on; a missing one answers 403 with details.reason API_KEY_PERMISSION_DENIED and details.required, and a key whose creator left the organization answers API_KEY_CREATOR_INACTIVE. The key''s accessLevel (full_access, run_workflows, read_only, or none) summarizes its permissions. Create a key at https://app.mindcloud.co/user/api-keys.'