toolaby-app Analytics API

openapi: 3.2.0
info:
  title: Toolaby Analytics API
  version: '2026-09-16'
  description: 'Look up whether a person holds a tool, and grant or revoke access. Keys are created under Configure → API and sent as a bearer token. Errors are `{ error: { type, message, param? } }`.'
servers:
- url: /
security:
- bearer: []
tags:
- name: Analytics
paths:
  /api/v1/tools/{slug}/analytics:
    get:
      tags:
      - Analytics
      summary: Analytics summary
      description: 'The Overview''s figures for the period: devices active today, in 7 and in 30 days, new devices; the funnel from a new device to paid; money in each currency with monthly recurring revenue; uninstalls. A part the plan does not hold is `null`, and `parts` says what each is to this workspace.'
      parameters:
      - schema:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{1,118}$
          example: invoice-grabber
          description: 'The tool id: the full one (acme--invoice-grabber) or the short one the dashboard shows (invoice-grabber).'
        required: true
        description: 'The tool id: the full one (acme--invoice-grabber) or the short one the dashboard shows (invoice-grabber).'
        name: slug
        in: path
      - schema:
          type: string
          enum:
          - 7d
          - 30d
          - 90d
          - 12m
          description: 'The period: the last 7 days, 30 (the default), 90, or 12 months, today the last of them. Never further back than the plan sees: Hobby sees 30 days.'
        required: false
        description: 'The period: the last 7 days, 30 (the default), 90, or 12 months, today the last of them. Never further back than the plan sees: Hobby sees 30 days.'
        name: range
        in: query
      - schema:
          type: string
          enum:
          - app
          - web
          description: 'Whose numbers: `app`, the extension''s devices; `web`, a web app''s signed-in buyers (each counted as one device). Both together where absent. Revenue is the tool''s whole either way, and uninstalls are the extension''s.'
        required: false
        description: 'Whose numbers: `app`, the extension''s devices; `web`, a web app''s signed-in buyers (each counted as one device). Both together where absent. Revenue is the tool''s whole either way, and uninstalls are the extension''s.'
        name: channel
        in: query
      responses:
        '200':
          description: The summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsSummary'
        '400':
          description: A parameter is missing or wrong; `param` names it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No key, a malformed key, or a revoked one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The workspace''s plan does not allow it: on Hobby, 100 passes at once.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such tool, grant or person in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: More than a minute's requests — 600 from this key, 1,200 from the workspace's keys together, 2,400 from its owner's — more than 30 pages of customers in a minute from the workspace, a tool's 1,000 grants in a day, or the workspace's 20,000 additions in a day.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Toolaby's fault, or it cannot count the workspace's additions just now. Retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getApiV1ToolsBySlugAnalytics
      x-operation-id-source: derived
  /api/v1/tools/{slug}/analytics/{table}:
    get:
      tags:
      - Analytics
      summary: Analytics table
      description: 'A table of Analytics as the CSV files hold it: `devices` and `cohorts` (Devices), `revenue` (Revenue), `features` (Features), `versions` (Versions), `uninstalls` (Uninstalls). Each is open where its part is.'
      parameters:
      - schema:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{1,118}$
          example: invoice-grabber
          description: 'The tool id: the full one (acme--invoice-grabber) or the short one the dashboard shows (invoice-grabber).'
        required: true
        description: 'The tool id: the full one (acme--invoice-grabber) or the short one the dashboard shows (invoice-grabber).'
        name: slug
        in: path
      - schema:
          type: string
          enum:
          - devices
          - cohorts
          - revenue
          - features
          - versions
          - uninstalls
          example: devices
        required: true
        name: table
        in: path
      - schema:
          type: string
          enum:
          - 7d
          - 30d
          - 90d
          - 12m
          description: 'The period: the last 7 days, 30 (the default), 90, or 12 months, today the last of them. Never further back than the plan sees: Hobby sees 30 days.'
        required: false
        description: 'The period: the last 7 days, 30 (the default), 90, or 12 months, today the last of them. Never further back than the plan sees: Hobby sees 30 days.'
        name: range
        in: query
      - schema:
          type: string
          enum:
          - app
          - web
          description: 'Whose numbers: `app`, the extension''s devices; `web`, a web app''s signed-in buyers (each counted as one device). Both together where absent. Revenue is the tool''s whole either way, and uninstalls are the extension''s.'
        required: false
        description: 'Whose numbers: `app`, the extension''s devices; `web`, a web app''s signed-in buyers (each counted as one device). Both together where absent. Revenue is the tool''s whole either way, and uninstalls are the extension''s.'
        name: channel
        in: query
      responses:
        '200':
          description: The rows, a row an object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsTable'
        '400':
          description: A parameter is missing or wrong; `param` names it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No key, a malformed key, or a revoked one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The workspace''s plan does not allow it: on Hobby, 100 passes at once.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such tool, grant or person in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: More than a minute's requests — 600 from this key, 1,200 from the workspace's keys together, 2,400 from its owner's — more than 30 pages of customers in a minute from the workspace, a tool's 1,000 grants in a day, or the workspace's 20,000 additions in a day.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Toolaby's fault, or it cannot count the workspace's additions just now. Retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getApiV1ToolsBySlugAnalyticsByTable
      x-operation-id-source: derived
components:
  schemas:
    AnalyticsSummary:
      type: object
      properties:
        tool:
          type: string
        range:
          $ref: '#/components/schemas/AnalyticsRange'
        channel:
          type:
          - string
          - 'null'
          enum:
          - app
          - web
          - null
          description: The channel asked for, or `null` for both together.
        counting:
          type: boolean
          description: Whether Toolaby counts devices yet. Revenue is counted regardless.
        parts:
          type: object
          additionalProperties:
            type: string
            enum:
            - open
            - locked
            - 'off'
        devices: {}
        funnel: {}
        revenue: {}
        uninstalls: {}
      required:
      - tool
      - range
      - channel
      - counting
      - parts
    AnalyticsTable:
      type: object
      properties:
        part:
          type: string
        range:
          $ref: '#/components/schemas/AnalyticsRange'
        channel:
          type:
          - string
          - 'null'
          enum:
          - app
          - web
          - null
          description: The channel asked for, or `null` for both together.
        data:
          type: array
          items:
            type: object
            additionalProperties: {}
      required:
      - part
      - range
      - channel
      - data
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - authentication_error
              - invalid_request_error
              - idempotency_error
              - plan_limit_error
              - not_found
              - rate_limit_error
              - api_error
            message:
              type: string
            param:
              type: string
          required:
          - type
          - message
      required:
      - error
    AnalyticsRange:
      type: object
      properties:
        id:
          type: string
        from:
          type: string
        to:
          type: string
        days:
          type: integer
        clamped:
          type: boolean
          description: Asked for further back than the plan sees, and given its furthest.
      required:
      - id
      - from
      - to
      - days
      - clamped
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: 'An API key from the dashboard: wk_test_… or wk_live_….'