Minubo Data API

openapi: 3.1.0
info:
  title: Minubo Auth Data API
  version: 1.0.0
  description: "# Getting Started\n\nBase URL: `https://api.minubo.com`\n\nThis reference combines multiple service specifications into one API view, including Auth, ETL, and the Data API.\n\n## Requirements\n\nTo use the minubo API, you need to have a valid token ID and token secret. Those can be obtained from the minubo Application by navigating to [Settings -> API Credentials](https://app.minubo.com/#/settings/tenant/apicredentials).\n## Authentication\n\nCreate a JWT using `POST /auth/v1/token`:\n\n```bash\ncurl -X POST \"https://api.minubo.com/auth/v1/token\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"tokenId\":\"<token-id>\",\"tokenSecret\":\"<token-secret>\"}'\n```\n\nUse the returned token as a bearer token for protected endpoints.\n\n## Examples\n\n### Trigger ETL and check status\n\n```python\nimport requests\n\nbase = \"https://api.minubo.com\"\n\n# Get valid token\ntoken = requests.post(\n    f\"{base}/auth/v1/token\",\n    json={\"tokenId\": \"<token-id>\", \"tokenSecret\": \"<token-secret>\"},\n).json()[\"token\"]\n\nheaders = {\"Authorization\": f\"Bearer {token}\"}\n\n# Trigger ETL process\nprocess_uuid = requests.post(\n    f\"{base}/etl/v1/process/start\",\n    headers=headers,\n).json()[\"processUuid\"]\n\n# Check status\nstatus = requests.get(\n    f\"{base}/etl/v1/process/status/{process_uuid}\",\n    headers=headers,\n).json()\nprint(status)\n```\n\n### Inspect schema and run a data query\n\n```python\nimport requests\n\nbase = \"https://api.minubo.com\"\n\n# Get valid token\ntoken = requests.post(\n    f\"{base}/auth/v1/token\",\n    json={\"tokenId\": \"<token-id>\", \"tokenSecret\": \"<token-secret>\"},\n).json()[\"token\"]\n\nheaders = {\"Authorization\": f\"Bearer {token}\"}\n\nschema = requests.get(\n    f\"{base}/data/v1/schema\",\n    headers=headers,\n).json()\n\nprint(schema[\"attributes\"][0])\n\nresult = requests.post(\n    f\"{base}/data/v1/query\",\n    headers={**headers, \"Content-Type\": \"application/json\"},\n    json={\n        \"attributes\": [\"prdNumber\"],\n        \"measures\": [\"omsOrdNum\"],\n        \"timeFilter\": {\n            \"from\": \"2026-01-01\",\n            \"to\": \"2026-01-31\"\n        },\n        \"limit\": 1000\n    },\n).json()\n\nprint(result)\n```\n\n### Troubleshooting\n\n- `401 Unauthorized`: generate a new token and update the bearer header.\n- `429 Too Many Requests`: Data API endpoints are rate-limited to 50 requests per 10 minutes per API token."
servers:
- url: https://api.minubo.com
security:
- etl_bearerAuth: []
- data_bearerAuth: []
tags:
- name: Data
  description: Data endpoints
paths:
  /data/v1/query:
    post:
      tags:
      - Data
      summary: Execute a data query
      description: '

        Execute a query against your minubo data.


        Use `GET /data/v1/schema` first to discover the attributes and measures available for your account. The schema response contains the field `code` values that can be used in `attributes`, `measures`, filters, and ordering. Authenticate with `/auth/v1/token` and send the returned JWT as a Bearer token.


        **Query limitations:**

        - At most 20 `attributes` and 20 `measures` are allowed per request.

        - `limit` must be between 0 and 200000.

        - `timeFilter` is required, and its `from` must not be after its `to`. The same applies to `comparisonTimeFilter` when provided.

        - `IN` and `NOT_IN` filters require a non-empty `values` list; `EXISTS` and `NOT_EXISTS` filters must not set `values`.

        - `orderBy.field` must reference one of the fields declared in `attributes` or `measures`.

        '
      operationId: data_query
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/data_DataQueryRequest'
        required: true
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_DataQueryResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_DataQueryResponse'
        '403':
          description: Field not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_DataQueryResponse'
        '422':
          description: Unprocessable query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_DataQueryResponse'
        '500':
          description: Unexpected internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_DataQueryResponse'
        '504':
          description: Backend timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_DataQueryResponse'
  /data/v1/schema:
    get:
      tags:
      - Data
      summary: Get data model schema
      description: '

        Return the data model schema available to your tenant.


        Call this endpoint before `POST /data/v1/query` to discover which attribute and measure codes can be queried. The response contains localized names (`nameEN`, `nameDE`) for display and stable `code` values for query requests. The schema only includes fields available for your tenant.

        '
      operationId: data_getSchema
      responses:
        '200':
          description: Schema retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_DataSchemaResponse'
        '500':
          description: Unexpected internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_DataSchemaResponse'
components:
  schemas:
    data_DataQueryOrderBy:
      type: object
      properties:
        field:
          type: string
        direction:
          type: string
          enum:
          - ASC
          - DESC
      required:
      - direction
    data_DataQueryResponse:
      type: object
      properties:
        rows:
          type: array
          items:
            $ref: '#/components/schemas/data_DataQueryRow'
      required:
      - rows
    data_DataQueryFilterEntry:
      type: object
      properties:
        attribute:
          type: string
        operator:
          type: string
          enum:
          - IN
          - NOT_IN
          - EXISTS
          - NOT_EXISTS
        values:
          type: array
          items:
            type: string
    data_DataQueryTimeFilterModel:
      type: object
      properties:
        from:
          type: string
          format: date
        to:
          type: string
          format: date
    data_DataSchemaFieldResponse:
      type: object
      properties:
        code:
          type: string
        nameEN:
          type: string
        nameDE:
          type: string
      required:
      - code
      - nameDE
      - nameEN
    data_DataSchemaResponse:
      type: object
      properties:
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/data_DataSchemaFieldResponse'
        measures:
          type: array
          items:
            $ref: '#/components/schemas/data_DataSchemaFieldResponse'
      required:
      - attributes
      - measures
    data_DataQueryRequest:
      type: object
      properties:
        attributes:
          type: array
          items:
            type: string
        measures:
          type: array
          items:
            type: string
        timeFilter:
          $ref: '#/components/schemas/data_DataQueryTimeFilterModel'
        comparisonTimeFilter:
          $ref: '#/components/schemas/data_DataQueryTimeFilterModel'
        filter:
          type: array
          items:
            $ref: '#/components/schemas/data_DataQueryFilterEntry'
        orderBy:
          $ref: '#/components/schemas/data_DataQueryOrderBy'
        limit:
          type: integer
          format: int32
      required:
      - attributes
      - filter
      - limit
      - measures
    data_DataQueryRow:
      type: object
      properties:
        attributes:
          type: object
          additionalProperties:
            type: string
        values:
          type: object
          additionalProperties:
            type: number
        comparison:
          type: object
          additionalProperties:
            type: number
      required:
      - attributes
      - values
  securitySchemes:
    etl_bearerAuth:
      type: http
      description: JWT Authorization header using the Bearer scheme. Can be retrieved by authenticating with the /auth/v1/token endpoint.
      in: header
      scheme: bearer
      bearerFormat: JWT
    data_bearerAuth:
      type: http
      description: JWT Authorization header using the Bearer scheme. Can be retrieved by authenticating with the /auth/v1/token endpoint.
      in: header
      scheme: bearer
      bearerFormat: JWT