openapi.yaml

openapi: 3.1.0
info:
  title: Visualizer API
  description: >
    Visualizer exposes a REST API for managing espresso shots, roasters, and coffee bag metadata.
    Authenticate with OAuth 2.0 access tokens issued by Visualizer or HTTP Basic using your account credentials.
  version: "1.0.0"
  contact:
    email: miha@visualizer.coffee
servers:
  - url: https://visualizer.coffee/api
    description: Production
  - url: http://localhost:3000/api
    description: Local development
tags:
  - name: Credentials
    description: Session and identity helpers.
  - name: Shots
    description: Access espresso shot exports and metadata.
  - name: Roasters
    description: Roaster catalog for the authenticated account.
  - name: Coffee Bags
    description: Coffee bag catalog scoped to a roaster.
paths:
  /me:
    get:
      tags:
        - Credentials
      summary: Get current user
      description: >
        Returns basic profile information for the authenticated account. Requires an OAuth token with the `read`
        scope or HTTP Basic credentials for a Visualizer account with password access.
      operationId: getMe
      security:
        - OAuth2:
            - read
        - BasicAuth: []
      responses:
        "200":
          description: Current account profile.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserSelf"
        "401":
          description: Authentication required.
  /shots:
    get:
      tags:
        - Shots
      summary: List shots
      description: >
        Returns a paginated list of shots visible to the caller. Anonymous clients receive only public shots.
        Authenticated users receive their own shots; non-premium accounts are limited to recent history while premium accounts see all data.
      operationId: listShots
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/ItemsParam"
        - $ref: "#/components/parameters/ShotSortParam"
      security:
        - OAuth2:
            - read
        - BasicAuth: []
        - {}
      responses:
        "200":
          description: Paginated shots.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ShotListResponse"
        "422":
          description: Pagination error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: Could not paginate
  /shots/{id}:
    parameters:
      - $ref: "#/components/parameters/ShotId"
    get:
      tags:
        - Shots
      summary: Retrieve a shot
      description: >
        Returns a single shot in Visualizer JSON format by default, or BeanConqueror JSON when `format=beanconqueror`.
        Set `essentials=true` to omit large brew data payloads.
      operationId: getShot
      parameters:
        - $ref: "#/components/parameters/ShotFormatParam"
        - $ref: "#/components/parameters/ShotEssentialsParam"
      security:
        - OAuth2:
            - read
        - BasicAuth: []
        - {}
      responses:
        "200":
          description: Shot payload in requested format.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ShotDetail"
                  - $ref: "#/components/schemas/ShotBeanconqueror"
              examples:
                visualizer:
                  summary: Visualizer format
                  value:
                    id: "c8fe2d3a-6d11-4a8f-9c73-1d4f6a0efb73"
                    user_id: "b82d57c1-5152-49b5-8c32-d5e686fac07b"
                    profile_title: "30g/60g/30s"
                    start_time: "2024-05-18T08:31:20Z"
                    updated_at: 1716021080
                    duration: 30.5
                    bean_weight: "18.0"
                    drink_weight: "40.0"
                    espresso_enjoyment: 8
                    roast_level: "Medium"
                    tags:
                      - morning
                    brewdata:
                      profile: "decent"
                beanconqueror:
                  summary: BeanConqueror format
                  value:
                    bean:
                      roaster: "Example Roaster"
                      name: "House Espresso"
                    brew:
                      grind_weight: 18
                      brew_beverage_quantity: 36
                    meta:
                      visualizer:
                        shot_id: "c8fe2d3a-6d11-4a8f-9c73-1d4f6a0efb73"
                        user_id: "b82d57c1-5152-49b5-8c32-d5e686fac07b"
                        updated_at: 1716021080
                        tags:
                          - morning
        "404":
          description: Shot not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      tags:
        - Shots
      summary: Delete a shot
      description: >
        Deletes a shot owned by the authenticated user. Requires the `write` scope when using OAuth.
      operationId: deleteShot
      security:
        - OAuth2:
            - write
        - BasicAuth: []
      responses:
        "200":
          description: Shot deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ShotDeleteResult"
        "401":
          description: Authentication required.
        "403":
          description: Missing `write` scope for the provided token.
        "404":
          description: Shot not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /shots/{id}/download:
    parameters:
      - $ref: "#/components/parameters/ShotId"
    get:
      tags:
        - Shots
      summary: Download a shot
      description: >
        Returns the same payload as `GET /shots/{id}` but served as a downloadable attachment.
      operationId: downloadShot
      parameters:
        - $ref: "#/components/parameters/ShotFormatParam"
        - $ref: "#/components/parameters/ShotEssentialsParam"
      security:
        - OAuth2:
            - read
        - BasicAuth: []
        - {}
      responses:
        "200":
          description: Shot payload attachment.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ShotDetail"
                  - $ref: "#/components/schemas/ShotBeanconqueror"
        "404":
          description: Shot not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /shots/{shot_id}/profile:
    parameters:
      - $ref: "#/components/parameters/ShotProfileId"
    get:
      tags:
        - Shots
      summary: Download a shot profile
      description: >
        Downloads a profile file associated with the shot. The response type depends on the underlying shot parser.
        Use `format=csv` for a CSV export (when available) or `format=json` to force JSON output for supported parsers.
      operationId: getShotProfile
      parameters:
        - $ref: "#/components/parameters/ShotProfileFormatParam"
      security:
        - OAuth2:
            - read
        - BasicAuth: []
        - {}
      responses:
        "200":
          description: Profile payload.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ShotProfileJson"
            text/csv:
              schema:
                $ref: "#/components/schemas/ShotProfileFile"
            application/x-tcl:
              schema:
                $ref: "#/components/schemas/ShotProfileFile"
            application/octet-stream:
              schema:
                $ref: "#/components/schemas/ShotProfileFile"
        "404":
          description: Shot not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: Profile is not available for the shot.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: Shot does not have a profile
  /shots/shared:
    get:
      tags:
        - Shots
      summary: Retrieve shared shots
      description: >
        Provide a `code` query parameter to retrieve the shot that was shared with that code. When no `code`
        is supplied, authenticated users receive every shot they have shared.
      operationId: getSharedShots
      parameters:
        - $ref: "#/components/parameters/ShotCodeParam"
        - $ref: "#/components/parameters/ShotFormatParam"
        - $ref: "#/components/parameters/ShotWithDataParam"
      security:
        - OAuth2:
            - read
        - BasicAuth: []
        - {}
      responses:
        "200":
          description: Shared shot payload(s).
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ShotDetail"
                  - $ref: "#/components/schemas/ShotBeanconqueror"
                  - $ref: "#/components/schemas/ShotSharedCollection"
        "404":
          description: Shared shot not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /shots/upload:
    post:
      tags:
        - Shots
      summary: Upload a shot file
      description: >
        Creates a new shot by uploading a Decent, BeanConqueror, Gaggiuino, or GaggiMate export. Provide either a multipart file upload using the `file` field or send the parsed JSON payload directly.
      operationId: uploadShot
      security:
        - OAuth2:
            - upload
        - OAuth2:
            - write
        - BasicAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Shot export file with JSON content.
          application/json:
            schema:
              $ref: "#/components/schemas/ShotUploadPayload"
      responses:
        "200":
          description: Shot successfully created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ShotUploadResult"
        "401":
          description: Authentication required.
        "403":
          description: Missing `upload` scope (or `write`) for the provided token.
        "422":
          description: Shot could not be processed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                missingFile:
                  summary: Missing file
                  value:
                    error: No shot file provided. Provide a file parameter with a multipart/form-data request or a JSON body with a valid JSON object.
                invalidFile:
                  summary: Invalid content
                  value:
                    error: Could not save the provided file. Bean weight can't be blank.
  /roasters:
    get:
      tags:
        - Roasters
      summary: List roasters
      description: Returns roasters owned by the authenticated user.
      operationId: listRoasters
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/ItemsParam"
      security:
        - OAuth2:
            - read
        - BasicAuth: []
      responses:
        "200":
          description: Paginated roasters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoasterListResponse"
        "401":
          description: Authentication required.
  /roasters/{id}:
    parameters:
      - $ref: "#/components/parameters/RoasterId"
    get:
      tags:
        - Roasters
      summary: Retrieve a roaster
      description: Fetches the specified roaster owned by the authenticated account, including website and image metadata when present.
      operationId: getRoaster
      security:
        - OAuth2:
            - read
        - BasicAuth: []
      responses:
        "200":
          description: Roaster details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoasterDetail"
        "401":
          description: Authentication required.
        "404":
          description: Roaster not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /roasters/{roaster_id}/coffee_bags:
    parameters:
      - $ref: "#/components/parameters/RoasterRef"
    get:
      tags:
        - Coffee Bags
      summary: List coffee bags
      description: Returns coffee bags for the given roaster, ordered by roast date with archived entries last.
      operationId: listCoffeeBags
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/ItemsParam"
      security:
        - OAuth2:
            - read
        - BasicAuth: []
      responses:
        "200":
          description: Paginated coffee bags.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CoffeeBagListResponse"
        "401":
          description: Authentication required.
        "404":
          description: Roaster not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /roasters/{roaster_id}/coffee_bags/{id}:
    parameters:
      - $ref: "#/components/parameters/RoasterRef"
      - $ref: "#/components/parameters/CoffeeBagId"
    get:
      tags:
        - Coffee Bags
      summary: Retrieve a coffee bag
      description: Returns detailed information for a coffee bag belonging to the given roaster, including origin, processing, and archival status.
      operationId: getCoffeeBag
      security:
        - OAuth2:
            - read
        - BasicAuth: []
      responses:
        "200":
          description: Coffee bag details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CoffeeBagDetail"
        "401":
          description: Authentication required.
        "404":
          description: Coffee bag not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: >
        Use your Visualizer email address and password. Two-factor authentication must be disabled for Basic authentication.
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://visualizer.coffee/oauth/authorize
          tokenUrl: https://visualizer.coffee/oauth/token
          refreshUrl: https://visualizer.coffee/oauth/token
          scopes:
            read: Read shots, roasters, coffee bags, and account metadata.
            upload: Upload shot files.
            write: Manage shots.
  parameters:
    PageParam:
      name: page
      in: query
      description: 1-based page number (defaults to 1).
      schema:
        type: integer
        minimum: 1
    ItemsParam:
      name: items
      in: query
      description: Items per page (defaults to 10, maximum 100).
      schema:
        type: integer
        minimum: 1
        maximum: 100
    ShotSortParam:
      name: sort
      in: query
      description: When set to `updated_at`, results are sorted by last update time; otherwise start time descending.
      schema:
        type: string
        enum:
          - updated_at
    ShotId:
      name: id
      in: path
      required: true
      description: Shot identifier.
      schema:
        type: string
        format: uuid
    ShotProfileId:
      name: shot_id
      in: path
      required: true
      description: Shot identifier.
      schema:
        type: string
        format: uuid
    ShotFormatParam:
      name: format
      in: query
      description: Response format for shot payloads.
      schema:
        type: string
        enum:
          - decent
          - beanconqueror
    ShotEssentialsParam:
      name: essentials
      in: query
      description: When true, omit brew telemetry from the response.
      schema:
        type: boolean
    ShotProfileFormatParam:
      name: format
      in: query
      description: Force a specific profile file format when available.
      schema:
        type: string
        enum:
          - csv
          - json
    ShotCodeParam:
      name: code
      in: query
      description: Four-character share code (case-insensitive).
      schema:
        type: string
        minLength: 4
        maxLength: 4
    ShotWithDataParam:
      name: with_data
      in: query
      description: When true, include brew telemetry in shared shot responses.
      schema:
        type: boolean
    RoasterId:
      name: id
      in: path
      required: true
      description: Roaster identifier.
      schema:
        type: string
        format: uuid
    RoasterRef:
      name: roaster_id
      in: path
      required: true
      description: Roaster identifier.
      schema:
        type: string
        format: uuid
    CoffeeBagId:
      name: id
      in: path
      required: true
      description: Coffee bag identifier.
      schema:
        type: string
        format: uuid
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
      example:
        error: Shot not found
    Paging:
      type: object
      required:
        - count
        - page
        - limit
        - pages
      properties:
        count:
          type: integer
          description: Total number of items.
        page:
          type: integer
          description: Current page number.
        limit:
          type: integer
          description: Number of items per page.
        pages:
          type: integer
          description: Total number of pages available.
    UserSelf:
      type: object
      required:
        - id
        - name
        - public
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        public:
          type: boolean
        avatar_url:
          type: string
          format: uri
          nullable: true
      example:
        id: "c2d5c71e-0e9f-4cbe-81bb-1db7c2422e23"
        name: "Ava Brewer"
        public: true
        avatar_url: "https://visualizer.coffee/uploads/avatars/ava.png"
    ShotSummary:
      type: object
      required:
        - id
        - clock
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        clock:
          type: integer
          format: int64
          description: Shot start time in seconds since the Unix epoch.
        updated_at:
          type: integer
          format: int64
          description: Last update time in seconds since the Unix epoch.
      example:
        id: "c8fe2d3a-6d11-4a8f-9c73-1d4f6a0efb73"
        clock: 1716021080
        updated_at: 1716022080
    ShotListResponse:
      type: object
      required:
        - data
        - paging
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ShotSummary"
        paging:
          $ref: "#/components/schemas/Paging"
    ShotVisualizerMeta:
      type: object
      required:
        - shot_id
        - user_id
        - updated_at
        - tags
      properties:
        shot_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        updated_at:
          type: integer
          format: int64
        duration:
          type: number
          nullable: true
        profile_title:
          type: string
          nullable: true
        start_time:
          type: string
          format: date-time
          nullable: true
        metadata:
          type: object
          nullable: true
          additionalProperties: true
        tags:
          type: array
          items:
            type: string
        profile_url:
          type: string
          format: uri
          nullable: true
        image_url:
          type: string
          format: uri
          nullable: true
        roaster_id:
          type: string
          format: uuid
          nullable: true
        coffee_bag_id:
          type: string
          format: uuid
          nullable: true
        user_name:
          type: string
          nullable: true
    ShotDetail:
      type: object
      required:
        - id
        - updated_at
        - tags
        - user_id
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        profile_title:
          type: string
          nullable: true
        start_time:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: integer
          format: int64
        duration:
          type: number
          nullable: true
        bean_brand:
          type: string
          nullable: true
        bean_type:
          type: string
          nullable: true
        bean_notes:
          type: string
          nullable: true
        bean_weight:
          type: string
          nullable: true
        drink_weight:
          type: string
          nullable: true
        drink_tds:
          type: string
          nullable: true
        drink_ey:
          type: string
          nullable: true
        espresso_enjoyment:
          type: integer
          nullable: true
        espresso_notes:
          type: string
          nullable: true
        grinder_model:
          type: string
          nullable: true
        grinder_setting:
          type: string
          nullable: true
        roast_date:
          type: string
          nullable: true
          description: Roast date formatted for the owner.
        roast_level:
          type: string
          nullable: true
        barista:
          type: string
          nullable: true
        metadata:
          type: object
          nullable: true
          additionalProperties: true
        tags:
          type: array
          items:
            type: string
        brewdata:
          type: object
          nullable: true
          additionalProperties: true
        timeframe:
          type: object
          nullable: true
          additionalProperties: true
        data:
          type: object
          nullable: true
          additionalProperties: true
        profile_url:
          type: string
          format: uri
          nullable: true
        image_url:
          type: string
          format: uri
          nullable: true
        roaster_id:
          type: string
          format: uuid
          nullable: true
        coffee_bag_id:
          type: string
          format: uuid
          nullable: true
        user_name:
          type: string
          nullable: true
      example:
        id: "c8fe2d3a-6d11-4a8f-9c73-1d4f6a0efb73"
        user_id: "b82d57c1-5152-49b5-8c32-d5e686fac07b"
        profile_title: "30g/60g/30s"
        start_time: "2024-05-18T08:31:20Z"
        updated_at: 1716021080
        duration: 30.5
        bean_brand: "Example Roasters"
        bean_type: "House Espresso"
        drink_weight: "40.0"
        espresso_enjoyment: 8
        tags:
          - morning
        metadata:
          group: "Competition"
        brewdata:
          profile: "decent"
    ShotBeanconqueror:
      type: object
      required:
        - meta
      properties:
        bean:
          type: object
          nullable: true
          additionalProperties: true
        brew:
          type: object
          nullable: true
          additionalProperties: true
        mill:
          type: object
          nullable: true
          additionalProperties: true
        preparation:
          type: object
          nullable: true
          additionalProperties: true
        timeframe:
          type: object
          nullable: true
          additionalProperties: true
        data:
          type: object
          nullable: true
          additionalProperties: true
        brewdata:
          type: object
          nullable: true
          additionalProperties: true
        meta:
          type: object
          required:
            - visualizer
          properties:
            visualizer:
              $ref: "#/components/schemas/ShotVisualizerMeta"
      example:
        bean:
          roaster: "Example Roaster"
          name: "House Espresso"
        brew:
          grind_weight: 18
          brew_beverage_quantity: 36
        preparation:
          name: "Decent DE1"
        meta:
          visualizer:
            shot_id: "c8fe2d3a-6d11-4a8f-9c73-1d4f6a0efb73"
            user_id: "b82d57c1-5152-49b5-8c32-d5e686fac07b"
            updated_at: 1716021080
            tags:
              - morning
    ShotSharedCollection:
      type: array
      items:
        $ref: "#/components/schemas/ShotDetail"
    ShotProfileJson:
      type: object
      additionalProperties: true
      description: JSON profile data emitted by supported integrations.
      example:
        name: "Turbo profile"
        steps:
          - temperature: 93
            seconds: 5
    ShotProfileFile:
      type: string
      format: binary
      description: Downloadable profile file (CSV, JSON, or TCL).
    ShotUploadPayload:
      type: object
      additionalProperties: true
      description: Raw JSON payload exported by supported devices or applications.
      example:
        bean:
          roaster: "Example Roaster"
          name: "House Espresso"
        brew:
          grind_weight: 18
          brew_beverage_quantity: 36
    ShotUploadResult:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
      example:
        id: "c8fe2d3a-6d11-4a8f-9c73-1d4f6a0efb73"
    ShotDeleteResult:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
      example:
        success: true
    RoasterSummary:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      example:
        id: "5f7b3f5a-2fb5-4531-9ee0-6f7e0e6bd2ef"
        name: "Example Roasters"
    RoasterListResponse:
      type: object
      required:
        - data
        - paging
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/RoasterSummary"
        paging:
          $ref: "#/components/schemas/Paging"
    RoasterDetail:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        website:
          type: string
          format: uri
          nullable: true
        image_url:
          type: string
          format: uri
          nullable: true
      example:
        id: "5f7b3f5a-2fb5-4531-9ee0-6f7e0e6bd2ef"
        name: "Example Roasters"
        website: "https://example.com"
        image_url: "https://visualizer.coffee/uploads/roasters/example.jpg"
    CoffeeBagSummary:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      example:
        id: "a07b5f68-21a5-4677-9eaf-cbc9f35b4b83"
        name: "Kenya AA (2024-01-05)"
    CoffeeBagListResponse:
      type: object
      required:
        - data
        - paging
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/CoffeeBagSummary"
        paging:
          $ref: "#/components/schemas/Paging"
    CoffeeBagDetail:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        roast_date:
          type: string
          format: date
          nullable: true
        roast_level:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
        farm:
          type: string
          nullable: true
        farmer:
          type: string
          nullable: true
        variety:
          type: string
          nullable: true
        elevation:
          type: string
          nullable: true
        processing:
          type: string
          nullable: true
        harvest_time:
          type: string
          nullable: true
        quality_score:
          type: string
          nullable: true
        tasting_notes:
          type: string
          nullable: true
        url:
          type: string
          format: uri
          nullable: true
        image_url:
          type: string
          format: uri
          nullable: true
        archived_at:
          type: string
          format: date-time
          nullable: true
      example:
        id: "a07b5f68-21a5-4677-9eaf-cbc9f35b4b83"
        name: "Kenya AA"
        roast_date: "2024-01-05"
        roast_level: "Light"
        country: "Kenya"
        region: "Nyeri"
        tasting_notes: "Blackberry, lime, honey"
        url: "https://example.com/bags/kenya-aa"
        image_url: "https://visualizer.coffee/uploads/bags/kenya-aa.jpg"
        archived_at: null