openapi: 3.1.0
info:
  title: 0pt Data OS API
  version: 1.0.0
  description: >
    SIAX Cloud Data OS — order-, estimat- och capability-API (0pt).
    Single Source of Truth för HTTP-kontraktet (SSOT). Routehandlers i
    app/api/* realiserar dessa kontrakt; se x-siax-status för vad som är
    live vs kontrakt-first (target).
  x-siax:
    appId: 0PT
    capabilityPrefix: 0pt
    tenantBinding: header X-Tenant-Id (live), session (target — se BACKLOG P0-2)
servers:
  - url: https://0pt.app
    description: Production (edge plane)
  - url: https://api.0pt.app
    description: Target API-host (Caddy, EJ verifierad live)
security:
  - bearerAuth: []
paths:
  /api/health:
    get:
      operationId: 0pt.health
      summary: Liveness + dependency state
      x-siax-status: live
      responses:
        "200":
          description: OK — db/queue rapporterar "configured"/"not_configured"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /api/estimates:
    post:
      operationId: 0pt.estimate_order
      summary: Prisestimat för en datajob-konfiguration
      x-siax-status: live
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EstimateRequest"
      responses:
        "200":
          description: Estimat (öre)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EstimateResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
  /api/orders:
    post:
      operationId: 0pt.create_order
      summary: Skapa draft-order (50 % deposition startar jobbet)
      x-siax-status: live
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateOrderRequest"
      responses:
        "201":
          description: Order skapad
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderSummary"
        "400":
          $ref: "#/components/responses/BadRequest"
    get:
      operationId: 0pt.list_orders
      summary: Lista ordrar (org-scoping saknas — se BACKLOG P0-3)
      x-siax-status: live
      x-siax-gap: S3 — ingen auth/org-scoping
      security: []
      responses:
        "200":
          description: Orderlista
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/OrderSummary"
  /api/orders/{id}:
    get:
      operationId: 0pt.get_order
      summary: Hämta order
      x-siax-status: live
      security: []
      parameters:
        - $ref: "#/components/parameters/OrderId"
      responses:
        "200":
          description: Order
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      operationId: 0pt.update_order
      summary: Uppdatera order
      x-siax-status: live
      security: []
      parameters:
        - $ref: "#/components/parameters/OrderId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Uppdaterad order
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          $ref: "#/components/responses/NotFound"
  /api/0pt:
    get:
      operationId: 0pt.capability_index
      summary: Capability-index
      x-siax-status: live
      responses:
        "200":
          description: Index med endpoints
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /api/0pt/sources/{sourceId}/query:
    post:
      operationId: 0pt.query_source
      summary: Bunden källfråga (enrich-primitiv)
      x-siax-status: live
      x-siax-gap: S10 — connection_config ur body (SSRF-primitiv, BACKLOG P0-7)
      parameters:
        - name: sourceId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SourceQueryRequest"
      responses:
        "200":
          description: Källdata med provenance per fält
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EnrichedRecord"
        "400":
          $ref: "#/components/responses/BadRequest"
  /api/0pt/documents/capture:
    post:
      operationId: 0pt.capture_document
      summary: Ta emot dokument (PII) för extraktion
      x-siax-status: live
      x-siax-gap: S2 — tenant_id från body (BACKLOG P0-2)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "201":
          description: Dokument registrerat
        "400":
          $ref: "#/components/responses/BadRequest"
    get:
      operationId: 0pt.list_documents
      summary: Lista dokument
      x-siax-status: live
      x-siax-gap: S2 — tenant_id från query (BACKLOG P0-2)
      responses:
        "200":
          description: Dokumentlista
  /api/0pt/documents/{documentId}/extraction:
    post:
      operationId: 0pt.extract_document
      summary: Extrahera dokument (OCR/AI — env-guardad, 501 utan konfig)
      x-siax-status: live
      parameters:
        - name: documentId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Extraktion — aldrig fabricerade värden
        "404":
          $ref: "#/components/responses/NotFound"
        "501":
          $ref: "#/components/responses/NotConfigured"
  /api/0pt/lakehouse/mappings:
    post:
      operationId: 0pt.map_dataset_to_iceberg
      summary: Registrera dataset↔Iceberg-mappning
      x-siax-status: live
      x-siax-gap: S2 — tenant_id från body (BACKLOG P0-2)
      responses:
        "201":
          description: Mappning registrerad
        "400":
          $ref: "#/components/responses/BadRequest"
    get:
      operationId: 0pt.list_iceberg_mappings
      summary: Lista mappningar
      x-siax-status: live
      x-siax-gap: S2 — tenant_id från query (BACKLOG P0-2)
      responses:
        "200":
          description: Mappningslista
  /api/0pt/lakehouse/mappings/{mappingId}/writes:
    post:
      operationId: 0pt.request_iceberg_write
      summary: Iceberg-write (L4) — tung variant delegeras till N0D-jobb
      x-siax-status: live
      x-siax-gap: S5 — CL0UD fail-open (BACKLOG P0-5)
      parameters:
        - name: mappingId
          in: path
          required: true
          schema:
            type: string
      responses:
        "202":
          description: Skrivning begärd (job_id eller synkront snapshot)
        "400":
          $ref: "#/components/responses/BadRequest"
  /api/0pt/sources/rate-policies:
    post:
      operationId: 0pt.create_rate_policy
      summary: Registrera käll-rate-policy
      x-siax-status: live
      x-siax-gap: S2 — tenant_id från body (BACKLOG P0-2)
      responses:
        "201":
          description: Rate-policy skapad
    get:
      operationId: 0pt.list_rate_policies
      summary: Lista rate-policies
      x-siax-status: live
      x-siax-gap: S2 — tenant_id från query (BACKLOG P0-2)
      responses:
        "200":
          description: Rate-policylista
  /api/screen:
    get:
      operationId: 0pt.screen_entity
      summary: Sanktions-/PEP-screening via OpenSanctions
      x-siax-status: live
      security: []
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Screeningträffar
        "400":
          $ref: "#/components/responses/BadRequest"
  /v1/0pt/enrichment/company-lists:
    post:
      operationId: 0pt.enrich_company_list
      summary: >
        (TARGET) Capability-formen av enrichment: lista → enrichade poster med
        bridge_provenance. Kontrakt-first — implementeras av 0pt-motor/edge
        via N0D-jobb (job_type 0pt.enrichment.company_list).
      x-siax-status: target
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EnrichCompanyListRequest"
      responses:
        "202":
          description: Jobb begärt — poll via /v1/0pt/jobs/{id} (target)
        "401":
          $ref: "#/components/responses/Unauthorized"
  /v1/0pt/resolve/entities:
    post:
      operationId: 0pt.resolve_entities
      summary: (TARGET) Entity resolution/dedupe (rapidfuzz idag, spaCy planerat)
      x-siax-status: target
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResolveEntitiesRequest"
      responses:
        "200":
          description: Kluster med konfidens
        "401":
          $ref: "#/components/responses/Unauthorized"
  /v1/0pt/provenance/records/{entityType}/{entityKey}:
    get:
      operationId: 0pt.get_provenance
      summary: (TARGET) Provenance per fält — bridge_provenance (källa, färskhet, konfidens, level)
      x-siax-status: target
      security: []
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
            enum: [company, contact, vehicle, ubo]
        - name: entityKey
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Provenance per fält
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProvenanceRecord"
        "401":
          $ref: "#/components/responses/Unauthorized"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Zitadel-utfärdad token; verifieras i middleware mot ZITADEL_ISSUER
  parameters:
    OrderId:
      name: id
      in: path
      required: true
      schema:
        type: string
  responses:
    BadRequest:
      description: Ogiltig input
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    Unauthorized:
      description: Saknad/ogiltig Bearer-token
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    NotFound:
      description: Resursen finns inte
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    NotConfigured:
      description: Integration ej konfigurerad (501)
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
  schemas:
    ErrorEnvelope:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code]
          properties:
            code:
              type: string
              description: error.code-envelope (t.ex. bad_json, storage_not_configured)
            message:
              type: string
    HealthResponse:
      type: object
      required: [ok, service, db, queue, ts]
      properties:
        ok:
          type: boolean
        service:
          type: string
        db:
          type: string
          enum: [configured, not_configured]
        queue:
          type: string
          enum: [configured, not_configured]
        ts:
          type: string
          format: date-time
    EstimateRequest:
      type: object
      properties:
        flow:
          type: string
        config:
          type: object
          additionalProperties: true
    EstimateResponse:
      type: object
      properties:
        estimate:
          type: object
          additionalProperties: true
    CreateOrderRequest:
      type: object
      properties:
        flow:
          type: string
          default: custom
        config:
          type: object
          additionalProperties: true
    OrderSummary:
      type: object
      required: [order_id, status]
      properties:
        order_id:
          type: string
        status:
          type: string
        deposit_ore:
          type: integer
          description: Deposition i öre
        total_ore:
          type: integer
          description: Totalsumma i öre
    Order:
      type: object
      properties:
        order_id:
          type: string
        status:
          type: string
        config:
          type: object
          additionalProperties: true
    SourceQueryRequest:
      type: object
      required: [tenant_id, source_id, query]
      properties:
        tenant_id:
          type: string
          description: (GAP) ska komma från session — BACKLOG P0-2
        project_id:
          type: string
        source_id:
          type: string
        query:
          type: string
        connection_config:
          type: object
          additionalProperties: true
          description: (GAP) SSRF-primitiv — BACKLOG P0-7
    EnrichedRecord:
      type: object
      properties:
        fields:
          type: object
          additionalProperties: true
        provenance:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/FieldProvenance"
    FieldProvenance:
      type: object
      required: [source_id, freshness, confidence, level]
      properties:
        source_id:
          type: string
        freshness:
          type: string
          format: date-time
        confidence:
          type: number
          minimum: 0
          maximum: 1
        level:
          type: integer
          minimum: 0
          maximum: 3
          description: 0=ej tillgänglig · 1=licensierad · 2=authorized web · 3=officiell API/bulk
    EnrichCompanyListRequest:
      type: object
      required: [market, entities]
      properties:
        market:
          type: string
        entities:
          type: array
          items:
            type: object
            additionalProperties: true
        fields:
          type: array
          items:
            type: string
        output_artifact_type:
          type: string
          default: st0re.artifact
    ResolveEntitiesRequest:
      type: object
      required: [records]
      properties:
        records:
          type: array
          items:
            type: object
            additionalProperties: true
        threshold:
          type: number
          default: 0.85
        algorithm:
          type: string
          enum: [rapidfuzz, target_spacy]
          default: rapidfuzz
    ProvenanceRecord:
      type: object
      additionalProperties:
        $ref: "#/components/schemas/FieldProvenance"