openapi: 3.0.3
info:
  title: UpKeep Assets Locations API
  description: UpKeep is an asset operations management and CMMS (Computerized Maintenance Management System) platform. The UpKeep API provides programmatic access to work orders, assets, parts, locations, preventive maintenance schedules, purchase orders, meters, and webhooks for maintenance teams and facility managers.
  version: '2022-09-14'
  contact:
    name: UpKeep Developer Support
    url: https://developers.onupkeep.com/
  termsOfService: https://upkeep.com/terms/
servers:
- url: https://api.onupkeep.com/api/v2
  description: UpKeep Production API
security:
- SessionToken: []
tags:
- name: Locations
  description: Location hierarchy management
paths:
  /locations:
    get:
      operationId: listLocations
      summary: List Locations
      description: Retrieve a list of locations in the location hierarchy.
      tags:
      - Locations
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        schema:
          type: integer
          default: 25
      - name: parentId
        in: query
        schema:
          type: string
        description: Filter by parent location
      responses:
        '200':
          description: List of locations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createLocation
      summary: Create Location
      description: Create a new location.
      tags:
      - Locations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationRequest'
      responses:
        '200':
          description: Location created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /locations/{id}:
    get:
      operationId: getLocation
      summary: Get Location
      description: Retrieve details of a specific location.
      tags:
      - Locations
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Location details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateLocation
      summary: Update Location
      description: Update an existing location.
      tags:
      - Locations
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationRequest'
      responses:
        '200':
          description: Location updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteLocation
      summary: Delete Location
      description: Delete a location.
      tags:
      - Locations
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Location deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Session token missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request body or parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    LocationRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        address:
          type: string
        parentId:
          type: string
    Location:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        address:
          type: string
        parentId:
          type: string
        createdAt:
          type: string
          format: date-time
    LocationList:
      type: object
      properties:
        success:
          type: boolean
        total:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Location'
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Error message
  securitySchemes:
    SessionToken:
      type: apiKey
      in: header
      name: session-token
      description: Session token obtained from POST /auth