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
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.
619 lines
18 KiB
YAML
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"
|