openapi: 3.2.0
info:
  title: MindCloud Public Usage 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: Usage
paths:
  /v2/usage:
    get:
      operationId: v2-get-usage
      summary: Get the company task usage summary for the current accounting period (trailing…
      description: 'Get the company task usage summary for the current accounting period (trailing 30 days): used tasks, task limit, and soft-limit flag.


        Requires the API key permission subscription:view.'
      tags:
      - Usage
      security:
      - apiKey:
        - subscription:view
      parameters:
      - $ref: '#/components/parameters/CompanyId'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/UsageSummary'
                  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
        default:
          description: Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/usage/daily:
    get:
      operationId: v2-get-usage-daily
      summary: Get the daily task usage series
      description: 'Get the daily task usage series. Defaults to the trailing 30 days; pass from/to (YYYY-MM-DD) to re-window. The window is capped at 45 days.


        Requires the API key permission subscription:view.'
      tags:
      - Usage
      security:
      - apiKey:
        - subscription:view
      parameters:
      - name: from
        in: query
        required: false
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: to
        in: query
        required: false
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - $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/DailyUsage'
                  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
        default:
          description: Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/usage/workflows:
    get:
      operationId: v2-get-usage-workflows
      summary: Get task usage broken down by workflow, highest first
      description: 'Get task usage broken down by workflow, highest first. Embedded usage is broken down further by installation inside each workflow. Defaults to the trailing 30 days; pass from/to (YYYY-MM-DD) to re-window. The window is capped at 45 days.


        Requires the API key permission subscription:view.'
      tags:
      - Usage
      security:
      - apiKey:
        - subscription:view
      parameters:
      - name: from
        in: query
        required: false
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: to
        in: query
        required: false
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - $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/WorkflowUsage'
                  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
        default:
          description: Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    WorkflowUsage:
      type: object
      properties:
        workflowId:
          type:
          - string
          - 'null'
          description: The workflow.
        name:
          type:
          - string
          - 'null'
          description: Its name.
        tasks:
          type:
          - integer
          - 'null'
          description: Tasks it used in the window.
        installations:
          type:
          - array
          - 'null'
          items:
            type: object
            properties:
              installationId:
                type:
                - string
                - 'null'
                description: The installation.
              name:
                type:
                - string
                - 'null'
                description: 'The installation label: the integration label template when one is set, otherwise "email - name" of the end user, otherwise the raw id.'
              integrationId:
                type:
                - string
                - 'null'
                description: The embedded integration the installation belongs to.
              integrationName:
                type:
                - string
                - 'null'
                description: That integration's name.
              tasks:
                type:
                - integer
                - 'null'
                description: Tasks the installation used in the window.
          description: 'Embedded usage per installation, highest first: installationId, name (the installation label), integrationId, integrationName, and tasks. Empty for workflows that did not run under an installation. Installation tasks add up to at most the workflow tasks; the remainder ran outside an installation or before meta.installationsFrom, the first day with installation detail.'
      required:
      - workflowId
      - name
      - tasks
      - installations
    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
    UsageSummary:
      type: object
      properties:
        periodStart:
          type:
          - string
          - 'null'
          description: First day of the current period.
        periodEnd:
          type:
          - string
          - 'null'
          description: Last day of the current period.
        usedTasks:
          type:
          - integer
          - 'null'
          description: Tasks used so far this period.
        taskLimit:
          type:
          - integer
          - 'null'
          description: Your task limit for the period.
        softLimitEnabled:
          type:
          - boolean
          - 'null'
          description: True when passing the limit warns instead of blocking.
      required:
      - periodStart
      - periodEnd
      - usedTasks
      - taskLimit
      - softLimitEnabled
    DailyUsage:
      type: object
      properties:
        date:
          type:
          - string
          - 'null'
          description: The day (YYYY-MM-DD).
        tasks:
          type:
          - integer
          - 'null'
          description: Tasks used that day.
      required:
      - date
      - tasks
  parameters:
    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).
  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.'