# Simpled.ai API reference *Updated 2026-08-25. Reference for the Simpled.ai public API: every endpoint, example requests, authentication, rate-limit headers, the RFC 9457 error format, and the versioning and deprecation policy.* The public API at https://simpled.ai/api/v1 answers questions about Simpled.ai -- what it does, what it can produce, what it costs -- as JSON. It is unauthenticated and read-only. Video generation is a separate, key-authenticated API; it is documented at the end of this page. ## Endpoints Every endpoint is a GET, returns application/json, and needs no credentials. Base URL: https://simpled.ai/api/v1 | Endpoint | Operation | Returns | | --- | --- | --- | | https://simpled.ai/api/v1 | getApiIndex | API index | | https://simpled.ai/api/v1/openapi.json | getOpenApiDocument | OpenAPI description | | https://simpled.ai/api/v1/health | getHealth | Liveness check | | https://simpled.ai/api/v1/company | getCompany | Company identity and contacts | | https://simpled.ai/api/v1/product | getProduct | What the product does | | https://simpled.ai/api/v1/capabilities | getCapabilities | Styles, languages, formats and durations | | https://simpled.ai/api/v1/pricing | getPricing | Plans and prices | | https://simpled.ai/api/v1/solutions | listSolutions | List solutions | | https://simpled.ai/api/v1/solutions/{slug} | getSolution | Get one solution | | https://simpled.ai/api/v1/guides | listGuides | List guides and comparisons | | https://simpled.ai/api/v1/guides/{slug} | getGuide | Get one guide | The same list is served as JSON from the API index, and as an OpenAPI 3.1 document. All three are generated from one registry, so they cannot disagree. ## Example requests Nothing here needs a key, a header, or a signup. ```bash # Discovery: every endpoint plus the rate-limit and versioning policy curl -s https://simpled.ai/api/v1 # What the product can produce curl -s https://simpled.ai/api/v1/capabilities # Current plans and prices -- quote from here, do not scrape the homepage curl -s https://simpled.ai/api/v1/pricing # One guide, as structured sections curl -s https://simpled.ai/api/v1/guides/vs-videoscribe # The OpenAPI description curl -s https://simpled.ai/api/v1/openapi.json # Inspect the rate-limit headers curl -sD - -o /dev/null https://simpled.ai/api/v1/health ``` ## Authentication The public API has no authentication. There is no key to request, no token to refresh, and no Authorization header to send. Any origin may call it: CORS is open, and the rate-limit and lifecycle headers are listed in Access-Control-Expose-Headers so a browser-based agent can read them. The generation API is different. It authenticates with an API key sent in the X-API-Key header, and keys are stored only as a SHA-256 hash. Request one at manav@simpled.ai. ## Rate limits 120 requests per 60 seconds per client address, under a policy named "public". Every response -- throttled or not -- carries both the current IETF draft headers and the de-facto ones, because different clients read different conventions. ```http HTTP/1.1 200 OK RateLimit-Policy: "public";q=120;w=60 RateLimit: "public";r=118;t=57 X-RateLimit-Limit: 120 X-RateLimit-Remaining: 118 X-RateLimit-Reset: 1787612841 Access-Control-Expose-Headers: RateLimit, RateLimit-Policy, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Deprecation, Sunset, Link, X-API-Version ``` The two conventions do NOT share reset semantics. The RateLimit header's t parameter is SECONDS REMAINING (draft-ietf-httpapi-ratelimit-headers-11 chose a delta so it does not depend on clock sync). X-RateLimit-Reset is an ABSOLUTE Unix epoch second, matching the GitHub convention. Read whichever you prefer, but do not treat them as the same number. ## Errors Errors are RFC 9457 problem documents with content-type application/problem+json. Exceeding the quota returns 429 with Retry-After in delta-seconds; Retry-After takes precedence over the RateLimit window, and the two values are always kept equal. ```http HTTP/1.1 429 Too Many Requests Content-Type: application/problem+json; charset=utf-8 Retry-After: 20 Cache-Control: no-store RateLimit: "public";r=0;t=20 { "type": "https://iana.org/assignments/http-problem-types#quota-exceeded", "title": "Request cannot be satisfied as assigned quota has been exceeded", "status": 429, "detail": "Quota of 120 requests per minute exhausted. Retry in 20 seconds.", "violated-policies": ["public"] } ``` A 404 on a templated path returns the same document shape, with an `available` array listing every valid identifier -- so a wrong slug is self-correcting. ## Versioning and deprecation Versioned by url path segment; v1 is current. These are the commitments, and they are what the headers below signal. ### Guarantee 1 A breaking change ships as a new version under a new path segment. The current version's response shapes never change incompatibly in place. ### Guarantee 2 A version is announced as deprecated at least 12 months before it stops responding. ### Guarantee 3 Additive changes -- new fields on an existing response, new endpoints -- are not breaking and ship without a version bump. ### Guarantee 4 Sunset is never earlier than Deprecation. ### How a deprecation is signalled Deprecation response header (RFC 9745), a Structured Fields Date such as @1788220799 - Sunset response header (RFC 8594), an IMF-fixdate such as Wed, 30 Dec 2026 23:59:59 GMT - Link header with rel="deprecation" pointing at the written policy -- sent on every response, including undeprecated ones - Link header with rel="sunset" once a retirement date is set - deprecated: true on the affected operations in the OpenAPI description ### Policy link on every response Every response -- including undeprecated ones -- carries Link: ; rel="deprecation". RFC 9745 permits this specifically so an API can publish its policy before anything is actually deprecated. Nothing is deprecated today, so no Deprecation or Sunset header is sent. ## What a deprecated version will look like When v1 is eventually superseded, its responses gain the headers below at least 12 months before it stops answering. Wire formats follow RFC 9745 and RFC 8594 exactly -- Deprecation is a Structured Fields Date, not an HTTP-date; Sunset is an IMF-fixdate with the literal GMT zone. ```http HTTP/1.1 200 OK Deprecation: @1798675199 Sunset: Thu, 30 Dec 2027 23:59:59 GMT Link: ; rel="deprecation"; type="text/html", ; rel="sunset"; type="text/html" X-API-Version: v1 ``` Deprecation @1798675199 is 30 December 2026; Sunset is 30 December 2027 -- the full notice period. Sunset is never earlier than Deprecation (RFC 9745 ยง4), and the affected operations are also marked deprecated: true in the OpenAPI description. ## Discovery Three registered link relations point at this API from anywhere on the domain: service-desc and service-doc (RFC 8631) and api-catalog (RFC 9727). The catalog at https://simpled.ai/.well-known/api-catalog answers both GET and HEAD, as RFC 9727 requires. ```bash curl -s https://simpled.ai/.well-known/api-catalog \ -H 'Accept: application/linkset+json' # The same links ride on every API response curl -sD - -o /dev/null https://simpled.ai/api/v1/health | grep -i '^link:' ``` ## The generation API Rendering runs on a separate host at https://api.simpled.ai, with its own OpenAPI document and Swagger UI. It is asynchronous: create a project, poll it, then fetch the MP4. Every minute of finished video costs one credit. ```bash # 1. Create -- returns a project_id immediately curl -s -X POST https://api.simpled.ai/v1.7/projects \ -H 'X-API-Key: wb_...' \ -H 'Content-Type: application/json' \ -d '{"topic":"Explain how compound interest works","duration_seconds":60,"video_format":"horizontal"}' # 2. Poll until status is "completed" curl -s https://api.simpled.ai/projects/PROJECT_ID -H 'X-API-Key: wb_...' # 3. Fetch the finished video curl -sL https://api.simpled.ai/projects/PROJECT_ID/video -H 'X-API-Key: wb_...' -o out.mp4 ``` Full interactive reference: https://api.simpled.ai/docs. Machine-readable: https://api.simpled.ai/openapi.json. ## Questions API questions, key requests and bug reports go to manav@simpled.ai. The developer hub at https://simpled.ai/developers has the wider picture, including the CLI and the agent instruction file.