Instadram Users API

openapi: 3.2.0
info:
  title: Instadram Users API
  version: 1.0.0
  description: REST API for managing bourbon collections, bottles, expressions, and cocktails
  contact:
    name: API Support
    email: support@instadram.me
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.instadram.me/v1
  description: Production server
- url: https://api-instadram-me.web.app/v1
  description: Firebase Hosting server
- url: https://us-central1-oldoak-collection.cloudfunctions.net/v1
  description: Firebase Functions server
- url: http://localhost:5001/oldoak-collection/us-central1/v1
  description: Local development server
tags:
- name: Users
  description: User profile and collection operations
paths:
  /api/v1/users/profile:
    get:
      summary: Get current user's profile
      tags:
      - Users
      security:
      - bearerAuth: []
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/UserProfile'
      operationId: getApiV1UsersProfile
      x-operation-id-source: derived
  /api/v1/users/{id}/collection:
    get:
      summary: Get a user's collection
      tags:
      - Users
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: User ID
      - in: query
        name: limit
        schema:
          type: integer
          default: 20
        description: Number of bottles to return
      - in: query
        name: offset
        schema:
          type: integer
          default: 0
        description: Number of bottles to skip
      responses:
        '200':
          description: User's collection
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/UserCollection'
      operationId: getApiV1UsersByIdCollection
      x-operation-id-source: derived
  /api/v1/users/following:
    get:
      summary: Get list of users the current user follows
      tags:
      - Users
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List of followed users
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      users:
                        type: array
                        items:
                          $ref: '#/components/schemas/FollowingUser'
                      total_count:
                        type: integer
      operationId: getApiV1UsersFollowing
      x-operation-id-source: derived
  /api/v1/users/search:
    get:
      summary: Search for users by username or display name
      tags:
      - Users
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: q
        required: true
        schema:
          type: string
        description: Username or display name to search for
      responses:
        '200':
          description: User search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      users:
                        type: array
                        items:
                          $ref: '#/components/schemas/UserProfile'
                      total_count:
                        type: integer
      operationId: getApiV1UsersSearch
      x-operation-id-source: derived
components:
  schemas:
    FollowingUser:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    Bottle:
      type: object
      properties:
        id:
          type: string
          description: Bottle ID
        name:
          type: string
          description: Bottle name
        distillery:
          type: string
          description: Distillery name
        proof:
          type: number
          description: Bottle proof
        notes:
          type: string
          description: User notes
        image_url:
          type: string
          description: Bottle image URL
        msrp:
          type: number
          description: Manufacturer suggested retail price
        msrp_source:
          type: string
          description: Source of MSRP information
        collection_ids:
          type: array
          items:
            type: string
          description: Collection IDs this bottle belongs to
        status:
          type: string
          enum:
          - unopened
          - opened
          - consumed
          - wishlist
          description: Bottle status
        is_favorite:
          type: boolean
          description: Whether bottle is favorited
        rating:
          type: number
          minimum: 1
          maximum: 5
          description: User rating (1-5)
        availability:
          type: string
          description: Bottle availability
        override_proof:
          type: number
          description: User override for proof
        purchase_price:
          type: number
          description: 'Purchase price. Owner-only: omitted when the caller is not the shelf owner'
        purchased_from:
          type: string
          description: 'Where the bottle was purchased. Owner-only: omitted when the caller is not the shelf owner'
        override_batch_number:
          type: string
          description: User override for batch number
        store_pick:
          type: boolean
          description: Whether this is a store pick
        store_pick_name:
          type: string
          description: Store pick name
        override_expression_name:
          type: string
          description: User override for expression name
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
    UserProfile:
      type: object
      properties:
        id:
          type: string
          description: User ID
        display_name:
          type: string
          description: User display name
        email:
          type: string
          description: User email
        photo_url:
          type: string
          description: User photo URL
        created_at:
          type: string
          format: date-time
          description: Account creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        collection_count:
          type: integer
          description: Number of collections
        bottle_count:
          type: integer
          description: Number of bottles
    UserCollection:
      type: object
      properties:
        user_id:
          type: string
          description: User ID
        user_name:
          type: string
          description: User name
        bottles:
          type: array
          items:
            $ref: '#/components/schemas/Bottle'
          description: User's bottles
        total_count:
          type: integer
          description: Total number of bottles
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Firebase Auth JWT token