openapi: 3.2.0
info:
  title: BodySpec Locations API
  description: This API allows BodySpec users to integrate their DEXA scan data with other platforms.
  license:
    name: Proprietary
  version: 0.18.2
servers:
- url: https://app.bodyspec.com
  description: Production server
security:
- OAuth2:
  - openid
  - profile
  - email
- BearerAuth: []
tags:
- name: Locations
  description: Browse and search scan locations
paths:
  /api/v1/locations:
    get:
      tags:
      - Locations
      summary: List locations
      description: Get a list of BodySpec scan locations with optional filtering by type and geographic proximity.
      operationId: _list_locations_api_v1_locations_get
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (starts at 1)
          default: 1
          title: Page
        description: Page number (starts at 1)
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page (max 100)
          default: 20
          title: Page Size
        description: Items per page (max 100)
      - name: location_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by type: ''mobile'' or ''storefront'''
          title: Location Type
        description: 'Filter by type: ''mobile'' or ''storefront'''
      - name: lat
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Latitude for geographic search
          title: Lat
        description: Latitude for geographic search
      - name: lng
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Longitude for geographic search
          title: Lng
        description: Longitude for geographic search
      - name: radius_miles
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            maximum: 500
            minimum: 0
          - type: 'null'
          description: Search radius in miles (max 500)
          title: Radius Miles
        description: Search radius in miles (max 500)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationsListResponse'
              example:
                locations:
                - location_id: abc123
                  name: BodySpec - San Francisco
                  location_type: storefront
                  address:
                    address_line1: 295 Broadway
                    city: San Francisco
                    state: CA
                    postal_code: '94108'
                    country: US
                  coordinates:
                    latitude: 37.7986
                    longitude: -122.4063
                  timezone: America/Los_Angeles
                  distance_miles: 1.23
                pagination:
                  page: 1
                  page_size: 20
                  has_more: true
        '400':
          description: Invalid request data
          content:
            application/json:
              example:
                detail:
                - loc:
                  - body
                  - phone
                  msg: string does not match regex
                  type: value_error.str.regex
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
  /api/v1/locations/{location_id}:
    get:
      tags:
      - Locations
      summary: Get location details
      description: Get detailed information about a specific location.
      operationId: _get_location_api_v1_locations__location_id__get
      parameters:
      - name: location_id
        in: path
        required: true
        schema:
          type: string
          title: Location Id
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationResponse'
              example:
                location:
                  location_id: abc123
                  name: BodySpec - San Francisco
                  location_type: storefront
                  address:
                    address_line1: 295 Broadway
                    city: San Francisco
                    state: CA
                    country: US
                  coordinates:
                    latitude: 37.7986
                    longitude: -122.4063
                  timezone: America/Los_Angeles
        '404':
          description: Resource not found
          content:
            application/json:
              example:
                detail: Location not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
components:
  schemas:
    LocationsListResponse:
      properties:
        locations:
          items:
            $ref: '#/components/schemas/Location'
          type: array
          title: Locations
        pagination:
          $ref: '#/components/schemas/Pagination'
      type: object
      required:
      - locations
      - pagination
      title: LocationsListResponse
      description: Response model for listing locations.
      x-internal: true
    Address:
      properties:
        address_line1:
          anyOf:
          - type: string
          - type: 'null'
          title: Address Line1
          description: Primary address line
        address_line2:
          anyOf:
          - type: string
          - type: 'null'
          title: Address Line2
          description: Secondary address line (e.g., suite number)
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
          description: City name
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
          description: State or province
        postal_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Postal Code
          description: Postal/ZIP code
        country:
          type: string
          title: Country
          description: Two-letter ISO country code
          default: US
      type: object
      title: Address
      description: Address information for a location.
      x-internal: true
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
      x-internal: true
    Coordinates:
      properties:
        latitude:
          type: number
          title: Latitude
          description: Latitude in decimal degrees
        longitude:
          type: number
          title: Longitude
          description: Longitude in decimal degrees
      type: object
      required:
      - latitude
      - longitude
      title: Coordinates
      description: Geographic coordinates for a location.
      x-internal: true
    Location:
      properties:
        location_id:
          type: string
          title: Location Id
          description: Unique identifier for the location
        name:
          type: string
          title: Name
          description: Location name
        location_type:
          type: string
          title: Location Type
          description: 'Type of location: ''mobile'' or ''storefront'''
        address:
          $ref: '#/components/schemas/Address'
          description: Address information
        coordinates:
          anyOf:
          - $ref: '#/components/schemas/Coordinates'
          - type: 'null'
          description: Geographic coordinates
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
          description: IANA timezone identifier (e.g., 'America/Los_Angeles')
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Public notes or description
        last_updated:
          type: string
          format: date-time
          title: Last Updated
          description: Last update timestamp in ISO 8601 UTC format
        distance_miles:
          anyOf:
          - type: number
          - type: 'null'
          title: Distance Miles
          description: Distance from search coordinates in miles. Only present when lat/lng search parameters are provided.
      type: object
      required:
      - location_id
      - name
      - location_type
      - address
      - last_updated
      title: Location
      description: Location model representing a scan location with full details.
    Pagination:
      properties:
        page:
          type: integer
          title: Page
          description: Current page number
        page_size:
          type: integer
          title: Page Size
          description: Number of items per page
        results:
          type: integer
          title: Results
          description: Number of results in this page
        has_more:
          type: boolean
          title: Has More
          description: Whether more results exist after this page
      type: object
      required:
      - page
      - page_size
      - results
      - has_more
      title: Pagination
      description: Pagination information for list responses.
      x-internal: true
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
      x-internal: true
    LocationResponse:
      properties:
        location:
          $ref: '#/components/schemas/Location'
      type: object
      required:
      - location
      title: LocationResponse
      description: Response model for getting a single location.
      x-internal: true
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth2 authentication via Keycloak with PKCE
      flows:
        authorizationCode:
          authorizationUrl: https://auth.bodyspec.com/realms/bodyspec/protocol/openid-connect/auth
          tokenUrl: https://auth.bodyspec.com/realms/bodyspec/protocol/openid-connect/token
          scopes:
            openid: OpenID Connect scope
            profile: Access to user profile
            email: Access to user email
          x-usePkce: SHA-256
          x-scalar-client-id: bodyspec-api-ext-v1
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token for authentication
    PartnerAuth:
      type: http
      scheme: basic
      description: For partner integrations only. Contact BodySpec to obtain credentials.
x-tagGroups:
- name: 👤 User Data
  tags:
  - Users
  - Appointments
  - Results
- name: 📅 Availability
  tags:
  - Locations
  - Services
  - Availability
- name: 🤝 Partners
  tags:
  - Reservations
  - Partner Users
  - Partner Appointments
  - Partner Results
  - Partner Intake
  - Partner Orders
  - Partner Webhooks
- name: 🏥 API Status
  tags:
  - API Status