Navigate Line items API

openapi: 3.1.0
info:
  title: NavigateAI Access codes Line items 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: Line items
paths:
  /v1/line_items:
    post:
      operationId: api_external_api_line_item_create_line_item_endpoint
      summary: Create a line item
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineItemRowApiResponse'
      tags:
      - Line items
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLineItemRequest'
        required: true
      security:
      - ApiKeyAuth: []
  /v1/line_items/{line_item_id}:
    post:
      operationId: api_external_api_line_item_update_line_item_row_endpoint
      summary: Update a line item
      parameters:
      - in: path
        name: line_item_id
        schema:
          title: Line Item Id
          type: string
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineItemRowApiResponse'
      tags:
      - Line items
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLineItemRowRequest'
        required: true
      security:
      - ApiKeyAuth: []
components:
  schemas:
    LineItemRowApiResponse:
      properties:
        line_item_row:
          $ref: '#/components/schemas/LineItemRowExternalSchema'
      required:
      - line_item_row
      title: LineItemRowApiResponse
      type: object
    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
    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
    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
    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
    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
    UpdateLineItemRowRequest:
      description: 'Request schema for updating a line item row.


        All fields are optional. Omitting a field leaves it unchanged.

        Some fields may be explicitly set to null to clear the value.'
      properties:
        title:
          description: Updated line item title. Omit to leave unchanged.
          title: Title
          type: string
        description:
          description: Updated line item description. Omit to leave unchanged.
          title: Description
          type: string
        price_reference_key:
          anyOf:
          - type: string
          - type: 'null'
          description: Pricing item reference key. Set to null to clear. Omit to leave unchanged.
          title: Price Reference Key
        notes:
          anyOf:
          - type: string
          - type: 'null'
          description: Line item notes. Set to null to clear. Omit to leave unchanged.
          title: Notes
        status:
          description: Updated line item status. Omit to leave unchanged.
          enum:
          - not_complete
          - complete
          - rejected
          title: Status
          type: string
        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). May only be set when the resulting line item status is `rejected`. Will be cleared otherwise. Omit to leave unchanged.
          title: Rejection Reason Option Id
        rejection_reason_text:
          anyOf:
          - type: string
          - type: 'null'
          description: Free text rejection reason for additional context. May only be set when the resulting line item status is `rejected`. Will be cleared otherwise. Omit to leave unchanged.
          title: Rejection Reason Text
      required: []
      title: UpdateLineItemRowRequest
      type: object
    CreateLineItemRequest:
      properties:
        scope_id:
          title: Scope Id
          type: string
        title:
          title: Title
          type: string
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        price_reference_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Price Reference Key
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
        custom_fields:
          anyOf:
          - type: object
          - type: 'null'
          title: Custom Fields
      required:
      - scope_id
      - title
      title: CreateLineItemRequest
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer