Files
0pt/contracts/openapi.yaml
T
admin a88ad04867
Security Scan (SIAX Cloud) / security (push) Successful in 21s
CI (SIAX Cloud) / security (push) Successful in 21s
CI (SIAX Cloud) / quality (push) Successful in 41s
CI (SIAX Cloud) / security (pull_request) Successful in 22s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 21s
CI (SIAX Cloud) / quality (pull_request) Successful in 41s
fix(health): report real per-dependency status instead of hardcoded ok:true
BACKLOG P0-3: /api/health only ever checked *presence* of DATABASE_URL/
REDIS_URL and always returned ok:true regardless of whether anything was
reachable -- ARCHITECTURE.md's own words, "an uptime monitor watching HTTP
200 would show green for a dying instance".

lib/health-checks.ts adds real dependency probes:
  - db: a live `select 1` round trip (not just DATABASE_URL presence)
  - engine: a real HTTP call to the FastAPI engine's own GET /health
  - stripe: Stripe's documented lightweight balance.retrieve() liveness call
  - queue: honestly reports "not_integrated" when REDIS_URL is set but
    unused -- no Redis client is wired anywhere in this repo, so reporting
    "ok" would fabricate a check that doesn't exist

/api/health stays a liveness check (always 200 while the process can
respond; the body's `ok` field is the honest signal). New GET /api/ready
fails closed with 503 when the load-bearing dependency (db) isn't both
configured and reachable -- the "no /ready route" gap.

contracts/openapi.yaml, docs/architecture/ARCHITECTURE.md, and docs/slo.md
updated to match. 17 new unit tests (dependency-injected fakes, no real
network/DB) + 5 route-level tests.
2026-08-11 13:49:23 +02:00

619 lines
18 KiB
YAML

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 + real per-dependency state
x-siax-status: live
security: []
responses:
"200":
description: Process is alive. Body reports honest per-dependency status (ok/error/not_configured/not_integrated) — see HealthResponse.
content:
application/json:
schema:
$ref: "#/components/schemas/HealthResponse"
/api/ready:
get:
operationId: 0pt.ready
summary: Readiness — fails closed when a load-bearing dependency is down
x-siax-status: live
security: []
responses:
"200":
description: Ready to serve real traffic.
content:
application/json:
schema:
$ref: "#/components/schemas/ReadyResponse"
"503":
description: Not ready — a load-bearing dependency is not configured/reachable.
content:
application/json:
schema:
$ref: "#/components/schemas/ReadyResponse"
/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
description: >
db/engine/stripe report a real dependency probe (BACKLOG P0-3): "ok"
means a live round trip succeeded, "error" means it was configured
but unreachable (see `detail`), "not_configured" means the env var
is unset. `queue` can only ever be "not_configured" or
"not_integrated" -- no Redis client is wired in this repo, so
presence of REDIS_URL is reported honestly rather than faking a
connectivity check. `ok` is true only when no configured dependency
is in "error". This is a LIVENESS check: HTTP status stays 200
whenever the process can respond, regardless of dependency state --
see /api/ready for the readiness gate that fails closed.
required: [ok, service, db, queue, engine, stripe, ts]
properties:
ok:
type: boolean
service:
type: string
db:
type: string
enum: [ok, error, not_configured]
queue:
type: string
enum: [not_configured, not_integrated]
engine:
type: string
enum: [ok, error, not_configured]
stripe:
type: string
enum: [ok, error, not_configured]
detail:
type: object
description: Present only when `ok` is false -- one-line error message per failing dependency.
additionalProperties:
type: string
ts:
type: string
format: date-time
ReadyResponse:
type: object
description: >
Readiness (BACKLOG P0-3: "no /ready route existed"). Fails closed --
503 whenever a load-bearing dependency (today: only `db`) is not
both configured and reachable. Point a load balancer / Coolify
readiness probe here, not at /api/health.
required: [ready, service, db, queue, engine, stripe, ts]
properties:
ready:
type: boolean
service:
type: string
db:
type: string
enum: [ok, error, not_configured]
queue:
type: string
enum: [not_configured, not_integrated]
engine:
type: string
enum: [ok, error, not_configured]
stripe:
type: string
enum: [ok, error, 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"