Navigate Scopes API

openapi: 3.1.0
info:
  title: NavigateAI Access codes Scopes API
  version: 1.0.0
  description: The NavigateAI external API allows you to programmatically manage locations, scoping, work orders, and more.
servers:
- url: https://api.navigateai.co
tags:
- name: Scopes
paths:
  /v1/scopes:
    post:
      operationId: api_external_api_scopes_create_scope_endpoint
      summary: Create a scope
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScopeResponse'
      tags:
      - Scopes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScopeRequest'
        required: true
      security:
      - ApiKeyAuth: []
    get:
      operationId: api_external_api_scopes_list_scopes_endpoint
      summary: List scopes
      parameters:
      - in: query
        name: limit
        schema:
          default: 50
          maximum: 1000
          minimum: 1
          title: Limit
          type: integer
        required: false
      - in: query
        name: cursor
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
        required: false
      - in: query
        name: location_id
        schema:
          anyOf:
          - items:
              type: string
            maxItems: 100
            minItems: 1
            type: array
          - type: 'null'
          title: Location Id
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListScopesResponse'
      tags:
      - Scopes
      security:
      - ApiKeyAuth: []
  /v1/scopes/{scope_id}:
    get:
      operationId: api_external_api_scopes_get_scope
      summary: Get a scope
      parameters:
      - in: path
        name: scope_id
        schema:
          title: Scope Id
          type: string
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScopeResponse'
      tags:
      - Scopes
      security:
      - ApiKeyAuth: []
components:
  schemas:
    ExternalVisitRequestStatus:
      description: 'Customer facing visit statuses. Each VisitRequestStatus should map directly to a ExternalVisitRequestStatus.

        But we don''t need ExternalVisitRequestStatus to directly map back to VisitRequestStatus.'
      enum:
      - visit_started
      - uploading
      - processing
      - in_review
      - completed
      - cancelled
      title: ExternalVisitRequestStatus
      type: string
    AudioEvidenceExternalSchema:
      properties:
        type:
          const: audio
          default: audio
          title: Type
          type: string
        start_ms:
          description: Start timestamp in the source video, in milliseconds.
          title: Start Ms
          type: integer
        end_ms:
          description: End timestamp in the source video, in milliseconds.
          title: End Ms
          type: integer
        text:
          description: Transcribed text from this audio segment.
          title: Text
          type: string
      required:
      - start_ms
      - end_ms
      - text
      title: AudioEvidence
      type: object
    VisitExternalSchema:
      properties:
        id:
          title: Id
          type: string
        type:
          deprecated: true
          description: 'Display name of the visit type. Deprecated: Prefer using visit_type instead.'
          title: Type
          type: string
        visit_type:
          $ref: '#/components/schemas/VisitTypeExternalSchema'
          description: The visit type for this visit.
        visit_request_status:
          $ref: '#/components/schemas/ExternalVisitRequestStatus'
        visited_at:
          format: date-time
          title: Visited At
          type: string
        visited_by:
          $ref: '#/components/schemas/UserExternalSchema'
        reviewed_by:
          anyOf:
          - $ref: '#/components/schemas/UserExternalSchema'
          - type: 'null'
          description: The user who reviewed and signed off on this visit, if any.
        video:
          anyOf:
          - $ref: '#/components/schemas/VideoExternalSchema'
          - type: 'null'
          description: The video captured during this visit, if any.
        product_url:
          description: Link to the NavigateAI dashboard for reviewing this visit.
          title: Product Url
          type: string
        product_pdf_url:
          description: Link to download a PDF report for this visit.
          title: Product Pdf Url
          type: string
        location_id:
          title: Location Id
          type: string
        work_order_id:
          anyOf:
          - type: string
          - type: 'null'
          description: The work order this visit is associated with, if any.
          title: Work Order Id
        access_code_metadata:
          anyOf:
          - type: object
          - type: 'null'
          description: Metadata from the access code that initiated this visit, if applicable.
          title: Access Code Metadata
        notes:
          anyOf:
          - type: string
          - type: 'null'
          description: Summary notes generated for this visit.
          title: Notes
        metadata:
          description: Additional structured data captured for this visit.
          title: Metadata
          type: object
      required:
      - id
      - type
      - visit_type
      - visit_request_status
      - visited_at
      - visited_by
      - video
      - product_url
      - product_pdf_url
      - location_id
      - work_order_id
      - access_code_metadata
      - notes
      - metadata
      title: Visit
      type: object
    CostComponentExternalSchema:
      description: A cost component representing a portion of a line item's pricing (e.g. labor, material).
      properties:
        kind:
          description: 'The type of cost component: "total", "labor", or "material".'
          enum:
          - total
          - labor
          - material
          title: Kind
          type: string
        label:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional display label for this component.
          title: Label
        unit_type:
          anyOf:
          - type: string
          - type: 'null'
          description: Unit of measurement (e.g. "each", "sqft"). Defaults to "each" if omitted.
          title: Unit Type
        unit_cost_in_cents:
          anyOf:
          - minimum: 0
            type: integer
          - type: 'null'
          description: Cost per unit in cents.
          title: Unit Cost In Cents
        quantity:
          description: Number of units as a decimal string (e.g. "1", "2.5").
          title: Quantity
          type: string
      required:
      - kind
      - quantity
      title: CostComponent
      type: object
    TextEvidenceExternalSchema:
      properties:
        type:
          const: text
          default: text
          title: Type
          type: string
        text:
          title: Text
          type: string
      required:
      - text
      title: TextEvidence
      type: object
    CreateScopeRequest:
      properties:
        location_id:
          title: Location Id
          type: string
      required:
      - location_id
      title: CreateScopeRequest
      type: object
    LineItemRowExternalSchema:
      properties:
        id:
          title: Id
          type: string
        line_item_row_id:
          description: The stable location-level line item ID.
          title: Line Item Row Id
          type: string
          x-excluded: true
        title:
          title: Title
          type: string
        description:
          title: Description
          type: string
        status:
          enum:
          - suggested
          - not_complete
          - complete
          - rejected
          title: Status
          type: string
        quantity:
          deprecated: true
          description: 'Deprecated: Use cost_components instead. Total quantity (integer).'
          title: Quantity
          type: integer
        unit_type:
          deprecated: true
          description: 'Deprecated: Use cost_components instead. Unit of measurement (e.g. "each", "sqft").'
          title: Unit Type
          type: string
        unit_cost_cents:
          anyOf:
          - type: integer
          - type: 'null'
          deprecated: true
          description: 'Deprecated: Use cost_components instead. Cost per unit in cents.'
          title: Unit Cost Cents
        cost_components:
          description: Granular cost breakdown. Replaces the legacy quantity/unit_type/unit_cost_cents fields.
          items:
            $ref: '#/components/schemas/CostComponentExternalSchema'
          title: Cost Components
          type: array
        price_override_reason:
          anyOf:
          - type: string
          - type: 'null'
          description: The reason recorded when a cost component's price was overridden (e.g. a labor cost change), if a reason was provided. Reflects the most recent price override. Null when no reason was recorded.
          title: Price Override Reason
        price_reference_key:
          anyOf:
          - type: string
          - type: 'null'
          description: Your external identifier for the pricing item used.
          title: Price Reference Key
        notes:
          title: Notes
          type: string
        custom_fields:
          title: Custom Fields
          type: object
        evidence:
          description: Supporting evidence — images, audio segments, or text notes.
          items:
            anyOf:
            - $ref: '#/components/schemas/ImageEvidenceExternalSchema'
            - $ref: '#/components/schemas/AudioEvidenceExternalSchema'
            - $ref: '#/components/schemas/TextEvidenceExternalSchema'
          title: Evidence
          type: array
        area_name:
          anyOf:
          - type: string
          - type: 'null'
          deprecated: true
          description: 'Deprecated: Use room.name instead. The room or area this line item applies to.'
          title: Area Name
        room:
          anyOf:
          - $ref: '#/components/schemas/LineItemRoomExternalSchema'
          - type: 'null'
          description: The room or area this line item applies to.
        rejection_reason_option_id:
          anyOf:
          - type: string
          - type: 'null'
          description: ID of the selected [rejection reason option](/api-reference/rejection-reason-options/rejection-reason-option-object), if applicable.
          title: Rejection Reason Option Id
        rejection_reason_text:
          anyOf:
          - type: string
          - type: 'null'
          description: Reason the line item was rejected, if applicable.
          title: Rejection Reason Text
        vendor:
          anyOf:
          - $ref: '#/components/schemas/VendorOrganizationExternalSchema'
          - type: 'null'
          description: The vendor assigned to this line item.
      required:
      - id
      - line_item_row_id
      - title
      - description
      - status
      - quantity
      - unit_type
      - unit_cost_cents
      - cost_components
      - price_reference_key
      - notes
      - custom_fields
      - evidence
      - area_name
      - room
      title: LineItemRow
      type: object
    LineItemRoomExternalSchema:
      description: The room or area a line item applies to.
      properties:
        name:
          description: Display name of the room or area (e.g. 'Bedroom 2', 'Kitchen'). Not guaranteed to be stable over time.
          title: Name
          type: string
        room_type_id:
          anyOf:
          - type: string
          - type: 'null'
          description: The [room type](/api-reference/room-types/room-type-object) ID.
          title: Room Type Id
      required:
      - name
      title: LineItemRoom
      type: object
    LocationExternalSchema:
      properties:
        id:
          title: Id
          type: string
        address_1:
          title: Address 1
          type: string
        address_2:
          anyOf:
          - type: string
          - type: 'null'
          title: Address 2
        city:
          title: City
          type: string
        state:
          title: State
          type: string
        zip_code:
          title: Zip Code
          type: string
        lat:
          anyOf:
          - type: number
          - type: 'null'
          title: Lat
        lon:
          anyOf:
          - type: number
          - type: 'null'
          title: Lon
        reference_key:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional unique identifier for this location in your system.
          title: Reference Key
        market_id:
          anyOf:
          - type: string
          - type: 'null'
          description: ID of the market this location belongs to.
          title: Market Id
        market_name:
          anyOf:
          - type: string
          - type: 'null'
          deprecated: true
          description: 'Deprecated: prefer market_id. Name of the geographic market this location belongs to.'
          title: Market Name
        custom_fields:
          anyOf:
          - type: object
          - type: 'null'
          description: Arbitrary key-value metadata. Supports partial updates.
          title: Custom Fields
      required:
      - id
      - address_1
      - address_2
      - city
      - state
      - zip_code
      - lat
      - lon
      - reference_key
      - market_id
      - market_name
      - custom_fields
      title: Location
      type: object
    ScopeThinExternalSchema:
      description: 'Lightweight scope schema for list endpoints.


        Related resources are referenced by id only; fetch the full object via its

        own endpoint when needed. This keeps list payloads small and avoids coupling

        list responses to the shapes of Location and Visit.


        Also intentionally omits workflow-ish fields like status and completed_by.

        Those semantics are still evolving, while this resource is meant to expose

        the stable customer-facing scope object.'
      properties:
        id:
          title: Id
          type: string
        created_at:
          format: date-time
          title: Created At
          type: string
        location_id:
          title: Location Id
          type: string
        initial_visit_id:
          anyOf:
          - type: string
          - type: 'null'
          description: The visit that produced this scope, if any.
          title: Initial Visit Id
      required:
      - id
      - created_at
      - location_id
      - initial_visit_id
      title: ScopeSummary
      type: object
    VendorOrganizationExternalSchema:
      properties:
        id:
          title: Id
          type: string
        name:
          title: Name
          type: string
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        reference_key:
          description: Optional unique identifier for this vendor in your system.
          title: Reference Key
          type: string
        is_enabled:
          description: Whether this vendor is enabled.
          title: Is Enabled
          type: boolean
        market_ids:
          description: IDs of the markets this vendor serves. A vendor with no market associations serves all markets.
          items:
            type: string
          title: Market Ids
          type: array
      required:
      - id
      - name
      - email
      - reference_key
      - is_enabled
      - market_ids
      title: Vendor
      type: object
    UserExternalSchema:
      properties:
        id:
          title: Id
          type: string
        email:
          title: Email
          type: string
        first_name:
          title: First Name
          type: string
        last_name:
          title: Last Name
          type: string
        reference_key:
          anyOf:
          - type: string
          - type: 'null'
          description: External identifier for this user.
          title: Reference Key
      required:
      - id
      - email
      - first_name
      - last_name
      - reference_key
      title: User
      type: object
    ScopeDetailExternalSchema:
      description: 'The full scope resource including line items, keyed by Scope.Id.


        This intentionally omits workflow-ish fields like status and completed_by.

        Those semantics are still evolving, while this resource is meant to expose

        the stable customer-facing scope object.'
      properties:
        id:
          title: Id
          type: string
        created_at:
          format: date-time
          title: Created At
          type: string
        location:
          $ref: '#/components/schemas/LocationExternalSchema'
        initial_visit:
          anyOf:
          - $ref: '#/components/schemas/VisitExternalSchema'
          - type: 'null'
          description: The visit that produced this scope.
        line_item_rows:
          description: Line items identified during the scope.
          items:
            $ref: '#/components/schemas/LineItemRowExternalSchema'
          title: Line Item Rows
          type: array
      required:
      - id
      - created_at
      - location
      - initial_visit
      - line_item_rows
      title: Scope
      type: object
    VisitTypeExternalSchema:
      properties:
        id:
          title: Id
          type: string
        display_name:
          title: Display Name
          type: string
        slug:
          description: URL-friendly identifier for this visit type.
          title: Slug
          type: string
      required:
      - id
      - display_name
      - slug
      title: VisitType
      type: object
    ListScopesResponse:
      properties:
        scopes:
          items:
            $ref: '#/components/schemas/ScopeThinExternalSchema'
          title: Scopes
          type: array
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      required:
      - scopes
      - next_cursor
      title: ListScopesResponse
      type: object
    ImageEvidenceExternalSchema:
      properties:
        type:
          const: image
          default: image
          title: Type
          type: string
        image_id:
          description: Use with the Get Image endpoint to retrieve the image file.
          title: Image Id
          type: string
        reference_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Reference Key
        visit_id:
          anyOf:
          - type: string
          - type: 'null'
          description: The visit this image was captured during.
          title: Visit Id
        is_selected:
          default: false
          description: Whether this image was explicitly selected as evidence.
          title: Is Selected
          type: boolean
        is_starred:
          default: false
          description: Whether this image was starred as the primary evidence photo.
          title: Is Starred
          type: boolean
      required:
      - image_id
      title: ImageEvidence
      type: object
    VideoExternalSchema:
      properties:
        id:
          title: Id
          type: string
        duration_ms:
          title: Duration Ms
          type: integer
        height:
          title: Height
          type: integer
        width:
          title: Width
          type: integer
      required:
      - id
      - duration_ms
      - height
      - width
      title: Video
      type: object
    ScopeResponse:
      properties:
        scope:
          $ref: '#/components/schemas/ScopeDetailExternalSchema'
      required:
      - scope
      title: ScopeResponse
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer