The public API contract* is the only documented external and AI-agent entry point for Ottili ONE. It is a sanitized subset of the internal Unified API: every endpoint it lists is approved for public use, and internal, admin-only, debug, raw-database, local and private-service routes are removed.
The canonical, version-controlled artifact is published at docs/api/openapi.public.json (with a YAML sibling docs/api/openapi.public.yaml) in the repository. The public production base URL is https://api.ottili.one.
What the contract contains
- Approved public routes* only — developer API, public content, platform, business, module and integration surfaces that are intended for external developers.
- Schemas and examples* referenced by those routes. Internal schema definitions that are not referenced by a public route are pruned so they are not leaked.
- Authentication* via the
securitySchemesblock (BearerAuthfor JWT/OAuth2,ApiKeyAuthfor developer API keys). See [Public API authentication](/docs/public-api-authentication) for the full flow. - Errors* using a structured envelope (
ok,error,code,request_id) with standard HTTP status codes (4xx client errors, 5xx server errors). - Rate limiting* documented in the contract description, enforced with adaptive limits and communicated through
X-RateLimit-Limit,X-RateLimit-RemainingandRetry-Afterheaders.
What the contract removes
The contract is produced by removing the following categories from the full Unified API specification. This directly addresses the public-website audit finding P0.2* (the public API reference previously exposed internal Unified API structure).
| Removed category | Examples |
|---|---|
| Internal admin routes | /api/v1/admin/*, /api/v1/platform/admin/* |
| Raw database routes | /api/v1/database/*, database pool endpoints |
| Duplicate-prefix (malformed) routes | /api/v1/api/v1/... |
| Debug / developer-debug routes | /api/v1/developer/debug/*, /debugging/* |
| Local filesystem / dev artifacts | /playwright, /fsevents, /sales_manager, /Ottili_ONE/... |
| Internal service surfaces | internal, ssh-surface, micro-evolution, stack-manager, simulation, wall-mode, dev-orchestrator, codehelm |
| Legacy unversioned routes | /api/company/*, /api/dashboard/*, /api/apps/*, /api/analytics/* |
| Migration / backfill routes | backfill, migration, /migrate, rollback |
| Spec-exposure / index management | /api/v1/docs/openapi/*, /docs/index/rebuild, /docs/index/stats |
Regenerating the contract
The published contract is generated, not hand-edited. After any change to the Unified API routes, regenerate it from the full spec:
python3 scripts/build_public_openapi.pyA contract test (tests/unit/test_public_openapi_contract.py) re-sanitizes the full spec and asserts the published artifact is byte-for-byte reproducible, contains no excluded routes, declares a production (non-localhost) server, and documents authentication, errors and rate limits. If the source changes and the contract is not regenerated, that test fails.
Status and follow-up
The sanitized, validated contract artifact is complete and committed. Serving only* this contract from the public API gateway (api.ottili.one) — instead of the full internal Unified API — is a separate deployment task so that external developers and agents can rely on the published surface.
Was this article helpful?