openapi: 3.2.0
info:
  title: MindCloud Public Child Companies 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: child-companies
paths:
  /v2/child-companies:
    get:
      operationId: v2-list-child-companies
      summary: List the child organizations of the key's company
      description: 'List the child organizations of the key''s company. Send a child''s id in X-Company-Id to call any other v2 endpoint on it with this key. Requires child_company:access on the key and its creator.


        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 child_company:access.'
      tags:
      - child-companies
      security:
      - apiKey:
        - child_company:access
      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, description, origin, linkedOn, memberCount, ownerCount.'
      - $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, description, origin, linkedOn, memberCount, ownerCount. Default: -linkedOn,id.'
      - name: where
        in: query
        required: false
        schema:
          type: string
          maxLength: 2048
        description: 'RSQL filter expression. Filterable fields: id, name, description, origin, linkedOn, memberCount, ownerCount. 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: description
        in: query
        required: false
        schema:
          type: string
        description: 'Filter on description: `description=value` matches it exactly. Bracket operators: `description[ne]`, `description[gt]`, `description[gte]`, `description[lt]`, `description[lte]`, `description[contains]`, `description[starts]`, `description[ends]`, and `description[in]` / `description[nin]` with comma-separated values.'
      - name: origin
        in: query
        required: false
        schema:
          type: string
          enum:
          - created
          - linked
        description: 'Filter on origin: `origin=value` matches it exactly. Bracket operators: `origin[ne]`, `origin[gt]`, `origin[gte]`, `origin[lt]`, `origin[lte]`, `origin[contains]`, `origin[starts]`, `origin[ends]`, and `origin[in]` / `origin[nin]` with comma-separated values.'
      - name: linkedOn
        in: query
        required: false
        schema:
          type: string
        description: 'Filter on linkedOn: `linkedOn=value` matches it exactly. A date or timestamp, such as 2026-10-01 or 2026-10-01T12:00:00Z. Bracket operators: `linkedOn[ne]`, `linkedOn[gt]`, `linkedOn[gte]`, `linkedOn[lt]`, `linkedOn[lte]`, and `linkedOn[in]` / `linkedOn[nin]` with comma-separated values.'
      - name: memberCount
        in: query
        required: false
        schema:
          type: integer
        description: 'Filter on memberCount: `memberCount=value` matches it exactly. Bracket operators: `memberCount[ne]`, `memberCount[gt]`, `memberCount[gte]`, `memberCount[lt]`, `memberCount[lte]`, and `memberCount[in]` / `memberCount[nin]` with comma-separated values.'
      - name: ownerCount
        in: query
        required: false
        schema:
          type: integer
        description: 'Filter on ownerCount: `ownerCount=value` matches it exactly. Bracket operators: `ownerCount[ne]`, `ownerCount[gt]`, `ownerCount[gte]`, `ownerCount[lt]`, `ownerCount[lte]`, and `ownerCount[in]` / `ownerCount[nin]` with comma-separated values.'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChildCompany'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
                required:
                - success
                - data
                - meta
        default:
          description: Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: v2-create-child-company
      summary: Create a new organization as a child of the key's company
      description: 'Create a new organization as a child of the key''s company. It starts with no members: invite people with POST /v2/members while sending the new id in X-Company-Id, which can seat its first Owner. Requires the key creator to hold child_company:manage.


        Requires the API key permission child_company:manage.'
      tags:
      - child-companies
      security:
      - apiKey:
        - child_company:manage
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 128
                description:
                  type: string
                  maxLength: 2048
              required:
              - name
      responses:
        '201':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/ChildCompany'
                  meta:
                    type: object
                    description: 'Response metadata, on endpoints that answer it: the usage window, a step count, or the provider paging of a Universal action run.'
                required:
                - success
                - data
        '400':
          description: The request body is invalid (INVALID_QUERY).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The API key lacks child_company:manage, or its creator no longer holds it (API_KEY_PERMISSION_DENIED), or the request named another company in X-Company-Id (COMPANY_SCOPE_MISMATCH).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The name is taken (COMPANY_NAME_TAKEN), this company is a personal account (COMPANY_PARENT_PERSONAL_FORBIDDEN), is itself a child (COMPANY_PARENT_DEPTH_EXCEEDED), or has reached its child limit (COMPANY_PARENT_CHILD_LIMIT_REACHED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: This company created its daily maximum of child organizations (CHILD_COMPANY_CREATION_LIMIT_REACHED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: The organization could not be created (COMPANY_REGION_PUBLISH_FAILED, CHILD_COMPANY_CREATE_FAILED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/child-companies/{companyId}:
    get:
      operationId: v2-get-child-company
      summary: Get one child organization of the key's company
      description: 'Get one child organization of the key''s company. Requires child_company:access on the key and its creator.


        Requires the API key permission child_company:access.'
      tags:
      - child-companies
      security:
      - apiKey:
        - child_company:access
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/ChildCompany'
                  meta:
                    type: object
                    description: 'Response metadata, on endpoints that answer it: the usage window, a step count, or the provider paging of a Universal action run.'
                required:
                - success
                - data
        '403':
          description: The API key lacks child_company:access, or its creator no longer holds it (API_KEY_PERMISSION_DENIED), or the request named another company in X-Company-Id (COMPANY_SCOPE_MISMATCH).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: This company has no active child organization with this id (NOT_FOUND).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: v2-release-child-company
      summary: 'Release a child organization: the link ends and this company''s keys can no…'
      description: 'Release a child organization: the link ends and this company''s keys can no longer reach it. The child organization and its data are not deleted. A child with no Owner cannot be released; seat one first. Requires the key creator to hold child_company:manage.


        Requires the API key permission child_company:manage.'
      tags:
      - child-companies
      security:
      - apiKey:
        - child_company:manage
      parameters:
      - name: companyId
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/DeletedResource'
                  meta:
                    type: object
                    description: 'Response metadata, on endpoints that answer it: the usage window, a step count, or the provider paging of a Universal action run.'
                required:
                - success
                - data
        '403':
          description: The API key lacks child_company:manage, or its creator no longer holds it (API_KEY_PERMISSION_DENIED), or the request named another company in X-Company-Id (COMPANY_SCOPE_MISMATCH).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: This company has no active child organization with this id (NOT_FOUND).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The child has no active Owner, so releasing it would leave it unreachable (CHILD_HAS_NO_OWNER).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        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).
  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
    DeletedResource:
      type: object
      properties:
        id:
          type: string
          description: The id of the resource that was deleted.
      required:
      - id
    ChildCompany:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: The child organization's id. Send it in X-Company-Id to call other endpoints on the child.
        name:
          type:
          - string
          - 'null'
          description: The child organization's name.
        description:
          type:
          - string
          - 'null'
          description: The child organization's description.
        origin:
          type:
          - string
          - 'null'
          enum:
          - created
          - linked
          - null
          description: created when your company created it through the API, linked when an existing organization accepted your company as its parent in Cirra.
        linkedOn:
          type:
          - string
          - 'null'
          format: date-time
          description: When the link started.
        memberCount:
          type:
          - integer
          - 'null'
          description: Members of the child organization, including pending invites.
        ownerCount:
          type:
          - integer
          - 'null'
          description: Active Owners. A child cannot be released while this is 0.
      required:
      - id
      - name
      - description
      - origin
      - linkedOn
      - memberCount
      - ownerCount
  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.'