Versioning policy
Overten uses URL-based versioning. Breaking changes always ship under a new URL prefix (/api/v2/*), and the previous version (/api/v1/*) remains live for at least 12 months after any major version bump.
What counts as a breaking change?
What counts as a breaking change?
Breaking changes are anything that would cause a correctly-written v1 client to fail or behave differently without code changes on your side. Examples include removing a field, renaming an endpoint, changing an HTTP method, or altering the shape of an error response.
What is always safe within v1?
What is always safe within v1?
Additive changes are always safe: new endpoints, new optional request fields, new response fields, new enum values, and new error codes. Write your client to ignore unknown fields and you will never be broken by an additive change.
How are breaking changes communicated?
How are breaking changes communicated?
Before anything is removed:
- An announcement appears here and is sent via email notice.
- Every affected response includes
X-Deprecated: trueandSunset: <date>headers for at least 12 months. - Removal only happens at the v2 boundary — never within v1.
v1.0.0-alpha — initial release
This is the initial public API surface. Everything listed below is new.Endpoints
The following endpoints are available in v1.0.0-alpha:| Endpoint | Description |
|---|---|
POST /signup | Creates a workspace org and your first API key in a single call (Firebase-authenticated) |
POST /organizations/{org_id}/api-keys | Mint a new API key for an org |
GET /organizations/{org_id}/api-keys | List API keys for an org |
DELETE /organizations/{org_id}/api-keys/{key_id} | Revoke an API key |
GET /verify | Validate a key and return org context |
POST /preflight | Dry-run a request through the LLM validator without spending credits |
POST /files | Upload a generic file |
POST /images | Upload an image with optional tags and caption |
GET /images | List images |
GET /images/{id} | Retrieve a single image |
DELETE /images/{id} | Delete an image |
POST /excel/generate | Generate an Excel workbook from a natural-language prompt |
POST /excel/analyze | Return a JSON answer by analyzing an uploaded workbook |
POST /word/generate | Generate a Word document from a natural-language prompt |
POST /slides/generate | Generate a PowerPoint presentation from a natural-language prompt |
POST /slides/outline | Generate a slide outline for preview-before-generate workflows |
GET /tasks/{task_id} | Poll the status of an async task |
GET /runs | List runs for your org |
GET /runs/{id} | Retrieve a single run |
GET /runs/{id}/download | Download the primary output file (follows a redirect) |
POST /runs/{id}/export | Export a run to an alternative format (PDF, CSV, PNG, etc.) |
POST /webhooks | Subscribe to run events |
GET /webhooks | List webhook subscriptions |
DELETE /webhooks | Remove a webhook subscription |
Features
Sync and async generation modes — every generation endpoint supports both modes. Passasync: true to queue the job immediately and poll GET /tasks/{task_id} for the result. Sync requests that exceed the 300-second ceiling automatically promote to async and return a 408 with a sync_timeout_upgrade_async error code.
Run resume semantics — pass a run_id on any generation request to iterate on the same document. The API uses the existing document as context so you do not have to re-explain the content or structure.
Preflight LLM validator — POST /preflight dry-runs your request through the same validator that runs before generation. It rejects requests that reference missing assets before spending any credits, letting you build a confirm-before-generate flow in your UI.
HMAC-signed webhooks — webhook payloads are signed with SHA-256 HMAC, include a replay-protection timestamp, and are retried up to 7 times with exponential backoff on delivery failure.
Credit ledger — every credit movement is logged for audit. You can inspect usage per run via the credits_used field on task and run objects.
Org-scoped tenancy — every resource lookup enforces that the calling org matches the resource’s owner org. There are no cross-tenant data leaks by design.
Embedded editor — every completed run includes an edit_url that you can load in an iframe to give your users an in-app editing experience.
Supported formats
| Format | Primary output | Export targets |
|---|---|---|
| Excel | .xlsx | PDF, CSV, PNG, HTML |
| Word | .docx | PDF, HTML, TXT, ODT |
| Slides | .pptx | PDF, PNG, ODP |
Current limitations
These are known constraints in the v1.0.0-alpha release. They do not represent the long-term roadmap — watch the changelog for updates.
- Personal vs. workspace key scoping — key scope is set at creation time via the dashboard. Every key inherits the creator’s current workspace role and cannot be re-scoped after minting.
- Text and static visuals only — audio and video generation are not supported in this release.
- Slides: maximum 30 slides per call — build larger decks in chunks by using
run_idresume to extend the same presentation across multiple calls. - Webhooks fire on
run.completedandrun.failedonly — intermediate status events (e.g.,run.started,run.progressed) are not available yet.
Follow releases
Stay up to date as the API evolves:- Follow @overten on X for release announcements.
- Join the Overten community to discuss changes, ask questions, and get early access to upcoming features.