openapi: 3.1.0
info:
  title: Spotr Developer Portal API
  version: 1.0.0
  description: >-
    Submit property analysis requests to Spotr and receive results via secure,
    signed webhooks. Authentication is via API key.
servers:
  - url: https://api.spotr.ai
    description: Production server
paths:
  /v1/requests:
    post:
      tags:
        - Requests
      summary: Create a new property analysis request
      operationId: createRequest
      security:
        - ApiKeyAuth: []
      requestBody:
        description: Request payload for property analysis
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestSchema'
      responses:
        '202':
          description: Request accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestCreationResponse'
              examples:
                success:
                  value:
                    request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        '401':
          description: Unauthorized — missing or invalid API key
        '422':
          description: Validation Error — invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key to authorize requests
  schemas:
    AddressBody:
      type: object
      title: AddressBody
      required:
        - country_code
        - city
        - street_name
        - street_number
        - postal_code
      properties:
        country_code:
          type: string
          pattern: ^\w{2}$
          description: 2-letter ISO 3166-1 alpha-2 country code
          example: NL
        city:
          type: string
          description: City name
          example: Amsterdam
        street_name:
          type: string
          description: Street name
          example: Main St
        street_number:
          type: string
          description: House or unit number
          example: '23'
        postal_code:
          type: string
          description: Postal code
          example: '2515'
        latitude:
          type:
            - number
            - 'null'
          minimum: -90
          maximum: 90
          description: Latitude (−90 to 90)
          example: 34.052235
        longitude:
          type:
            - number
            - 'null'
          minimum: -180
          maximum: 180
          description: Longitude (−180 to 180)
          example: -118.243683
    RequestSchema:
      type: object
      title: RequestSchema
      required:
        - address
        - package_names
      properties:
        portfolio_id:
          type:
            - string
            - 'null'
          description: Optional portfolio identifier
          example: '12345'
        address:
          $ref: '#/components/schemas/AddressBody'
          description: Property address to analyze
        package_names:
          type: array
          minItems: 1
          maxItems: 10
          description: Names of analysis packages to apply
          items:
            type: string
            enum:
              - base
              - fire_risk
              - rebuild_value
              - underwriting_risk
              - condition
              - materialisation
    RequestCreationResponse:
      type: object
      title: RequestCreationResponse
      required:
        - request_id
      properties:
        request_id:
          type: string
          format: uuid
          description: Unique identifier for the submitted request
    ValidationError:
      type: object
      title: ValidationError
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
          description: Location of the error in request payload
        msg:
          type: string
          description: Validation error message
        type:
          type: string
          description: Error type
    HTTPValidationError:
      type: object
      title: HTTPValidationError
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
