{"openapi":"3.1.0","info":{"title":"waybill.ge public API","description":"Public HTTP surface of waybill.ge - the hosted MCP server that lets AI agents manage Georgian RS.GE electronic waybills.\n\n**The primary programmatic surface is MCP**, not REST: connect an MCP client to `/mcp/` (streamable HTTP) using OAuth 2.1 or an API key, and call the typed waybill tools. This document describes the small unauthenticated REST surface that exists alongside it.\n\n- Agent index: [/llms.txt](/llms.txt)\n- Developer guide (auth, quotas, tools): [/developers](/developers)\n- OAuth discovery: `/.well-known/oauth-protected-resource/mcp/`\n\n**Versioning & deprecation**: the REST surface is versioned in the URL path (`/api/v1/`). Response shapes only grow within a version. Removals are announced at least 6 months ahead via `Deprecation` and `Sunset` headers (RFC 8594) and on /developers.\n\n**Rate limits**: `/api/v1/*` responses carry `RateLimit-*` headers; 429 responses include `Retry-After`.","version":"1.0.0"},"servers":[{"url":"https://waybill.ge"}],"paths":{"/api/v1/plans":{"get":{"tags":["public"],"summary":"List public plans","description":"The current plan catalog: names, monthly prices in GEL, and included MCP tool-call quotas. Unauthenticated; sourced from the same constants the pricing page renders, so it never drifts from the UI. Rate limited per client IP (see RateLimit-* headers).","operationId":"list_plans","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlansResponse"}}}}}}},"/health":{"get":{"tags":["meta"],"summary":"Service health","description":"Liveness + dependency probe.\n\nReturns 200 as long as the database is reachable. ``wsdl`` and\n``flitt`` are best-effort upstream checks reported in the body for\nthe dashboard / alerting layer; their failures do not flip the\nresponse code so Railway healthchecks tolerate transient flaps.","operationId":"get_health","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"Database unreachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}}},"components":{"schemas":{"DependencyCheck":{"properties":{"ok":{"type":"boolean","title":"Ok","description":"Whether the dependency responded healthily."},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"Failure detail (truncated); null when ok."}},"type":"object","required":["ok"],"title":"DependencyCheck","description":"One dependency probe result."},"HealthResponse":{"properties":{"ok":{"type":"boolean","title":"Ok","description":"True when every dependency is green."},"db":{"$ref":"#/components/schemas/DependencyCheck","description":"Database (hard dependency - gates the status code)."},"wsdl":{"$ref":"#/components/schemas/DependencyCheck","description":"RS.GE WSDL reachability (informational)."},"flitt":{"$ref":"#/components/schemas/DependencyCheck","description":"Payment provider reachability (informational)."},"build":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Build","description":"Commit SHA of the running build, or null when unknown. Consumers that attribute results to a commit must fail closed on null."}},"type":"object","required":["ok","db","wsdl","flitt"],"title":"HealthResponse","description":"Response of ``GET /health`` (200 healthy / 503 DB down)."},"PlanModel":{"properties":{"slug":{"type":"string","title":"Slug","description":"Stable plan identifier (trial, starter, pro)."},"name":{"type":"string","title":"Name","description":"Human-readable display name."},"price_gel":{"type":"number","title":"Price Gel","description":"Monthly price in Georgian Lari (GEL). 0 for the trial."},"currency":{"type":"string","title":"Currency","description":"ISO currency code of price_gel. Always GEL at launch."},"monthly_quota":{"type":"integer","title":"Monthly Quota","description":"Included MCP tool calls per billing period."},"max_api_keys":{"type":"integer","title":"Max Api Keys","description":"How many concurrent API keys the plan allows."},"trial_days":{"type":"integer","title":"Trial Days","description":"Trial length in days; 0 when the plan has no trial component."}},"type":"object","required":["slug","name","price_gel","currency","monthly_quota","max_api_keys","trial_days"],"title":"PlanModel","description":"One purchasable (or trial) plan tier."},"PlansResponse":{"properties":{"ok":{"type":"boolean","title":"Ok","description":"Always true on success."},"plans":{"items":{"$ref":"#/components/schemas/PlanModel"},"type":"array","title":"Plans","description":"Publicly purchasable plans plus the free trial."}},"type":"object","required":["ok","plans"],"title":"PlansResponse","description":"Response of ``GET /api/v1/plans``."}},"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth 2.1 authorization-code flow with PKCE for the MCP endpoint (/mcp/). Dynamic client registration (RFC 7591) is supported at /register. Within the `mcp` scope, tool access is further constrained by the tenant's plan: trial tenants get read + draft tools; write tools require a paid plan.","flows":{"authorizationCode":{"authorizationUrl":"https://waybill.ge/authorize","tokenUrl":"https://waybill.ge/token","scopes":{"mcp":"Access the tenant's RS.GE waybill tools over MCP (plan-gated read/draft/write)."}}}},"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"rsk_live_...","description":"Tenant-scoped API key minted in the dashboard (/dashboard/keys), sent as a Bearer token to /mcp/. Revocable at any time; inherits the same plan-based tool gating as OAuth tokens."}}}}