# Public API and integration boundary

> What is exposed to the app today and what should not be treated as a public integration contract.

Canonical: https://docs.onira.studio/reference/public-api-and-integration-boundary
Section: reference

Onira's web app communicates with the backend through authenticated GraphQL operations and a small number of app-owned HTTP endpoints. These interfaces power the product UI. They should not be treated as a stable public third-party API unless Onira explicitly publishes one.

## Current app boundary

The app uses:

- Authenticated GraphQL over HTTP for most product operations.
- A WebSocket ticket endpoint for realtime authenticated updates.
- Stripe-hosted checkout and billing portal redirects.
- App routes scoped by workspace slug.
- Project, character, voice, billing, render, and Studio operations through the product backend.

These interfaces are versioned for the product, not for external integrators.

## Workspace slugs

Authenticated app routes include the workspace slug. The slug resolves to an organization internally and keeps navigation workspace-aware.

When linking inside the app, preserve the workspace slug. Cross-workspace links can point users to the wrong projects, settings, or billing state.

## GraphQL use

The frontend uses generated GraphQL operations for typed reads and writes. Browser requests go through the app's GraphQL route.

Do not build external automation against internal operation names, generated types, or local schema details unless the Onira team has explicitly approved that integration.

## Realtime updates

Long-running production and Studio work can update through polling, snapshots, or realtime channels. The UI is designed to tolerate stage changes, retries, and streamed assistant responses.

External tools should not assume a single synchronous request creates a finished video.

## Billing integrations

Billing actions redirect to Stripe. Stripe is the source for hosted payment, invoice, subscription, and portal flows. Onira is the source for workspace credit interpretation, frozen credits, run caps, and project usage.

When reconciling billing, check both the Stripe-facing invoice state and the Onira workspace billing view.

## Stable user-facing contract

The stable user-facing contract is the product workflow:

1. Set up a workspace.
2. Create or choose saved characters when needed.
3. Start a production from the composer.
4. Review and approve the blueprint when enabled.
5. Refine the project in Studio.
6. Render an export.
7. Manage credits, invoices, and plan changes in Billing.

Anything deeper than that should be treated as implementation detail until a public integration API is documented.

## Product and publication boundary

- Onira produces a reviewable MP4; it does not upload or schedule social posts.
- Creators remain responsible for facts, sources, rights, disclosure, policy review, and final publication.
- Research is research-assisted; creator verification is required before publication.
- Onira does not guarantee factual accuracy, legal clearance, monetization, reach, or production success.
- The current Timeline and Studio surfaces support defined review and regeneration workflows, not arbitrary nonlinear editing.