openapi: 3.2.0
info:
  title: Finn-.com Tannlege API
  description: REST API for Norwegian dental clinic discovery, sourced from Brreg, HPR, and direct enrichment. All read endpoints are public; no authentication required.
  version: 0.1.0
  contact:
    url: https://finn-tannlege.com/kontakt
  license:
    name: CC0 (Brreg data)
    url: https://creativecommons.org/publicdomain/zero/1.0/
servers:
- url: https://finn-tannlege.com
  description: Production
tags:
- name: Tannlege
paths:
  /api/tannlege/agents:
    get:
      operationId: listDentalAgents
      summary: List / search dental clinics
      description: Returns a paginated list of dental clinics. All parameters are optional and combinable.
      parameters:
      - name: q
        in: query
        description: Free-text search (name or city)
        schema:
          type: string
        example: Oslo tannklinikk
      - name: fylke
        in: query
        description: County name (e.g. «Oslo», «Vestland»)
        schema:
          type: string
        example: Vestland
      - name: specialty
        in: query
        description: Specialty slug (e.g. «kjeveortopedi», «endodonti»)
        schema:
          type: string
        example: kjeveortopedi
      - name: helfo
        in: query
        description: '"true" to include only Helfo-agreement clinics'
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: acute_vakt
        in: query
        description: 1 to include only emergency-duty clinics
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: enrichment_state
        in: query
        description: Filter by enrichment state
        schema:
          type: string
          enum:
          - raw
          - enriched
          - thin_site
      - name: limit
        in: query
        description: Max results (default 50, max 500)
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 500
      - name: offset
        in: query
        description: Pagination offset
        schema:
          type: integer
          default: 0
          minimum: 0
      responses:
        '200':
          description: Array of dental clinic objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DentalClinic'
      tags:
      - Tannlege
  /api/tannlege/agents/{id}:
    get:
      operationId: getDentalAgent
      summary: Get a single clinic by ID
      parameters:
      - name: id
        in: path
        required: true
        description: Clinic UUID
        schema:
          type: string
      responses:
        '200':
          description: Dental clinic object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DentalClinic'
        '404':
          description: Not found
      tags:
      - Tannlege
  /api/tannlege/agents/{id}/specialists:
    get:
      operationId: getDentalSpecialists
      summary: List registered specialists at a clinic
      parameters:
      - name: id
        in: path
        required: true
        description: Clinic UUID
        schema:
          type: string
      responses:
        '200':
          description: Array of specialist records
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    specialty:
                      type: string
      tags:
      - Tannlege
  /api/tannlege/chains:
    get:
      operationId: listDentalChains
      summary: List all dental chains
      description: Returns distinct chain brands with clinic counts.
      responses:
        '200':
          description: Array of chain objects
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    chain_brand:
                      type: string
                    count:
                      type: integer
      tags:
      - Tannlege
  /api/tannlege/discover:
    get:
      operationId: discoverDentalAgents
      summary: Discover clinics (A2A-friendly discovery endpoint)
      description: Alias for /api/tannlege/agents; intended for agent discovery workflows.
      parameters:
      - name: q
        in: query
        schema:
          type: string
      - name: fylke
        in: query
        schema:
          type: string
      - name: specialty
        in: query
        schema:
          type: string
      - name: helfo
        in: query
        schema:
          type: string
      - name: acute_vakt
        in: query
        schema:
          type: integer
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Discovery result
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/DentalClinic'
      tags:
      - Tannlege
components:
  schemas:
    DentalClinic:
      type: object
      properties:
        id:
          type: string
          description: UUID
        org_nr:
          type: string
          description: 9-digit Norwegian organisation number
        navn:
          type: string
          description: Clinic name
        poststed:
          type: string
        fylke:
          type: string
        adresse:
          type: string
          nullable: true
        telefon:
          type: string
          nullable: true
        hjemmeside:
          type: string
          nullable: true
        helfo_agreement:
          type: string
          enum:
          - 'true'
          - 'false'
          - unknown
        acute_vakt:
          type: integer
          nullable: true
        available_specialties:
          type: array
          items:
            type: string
        chain_brand:
          type: string
          nullable: true
        is_chain_member:
          type: integer
        verification_status:
          type: string
        enrichment_state:
          type: string
        lat:
          type: number
          nullable: true
        lng:
          type: number
          nullable: true