docs: remove fabrications; document video, workflows, URL rendering, SDKs - #4
Open
suyash-thakur wants to merge 12 commits into
Open
docs: remove fabrications; document video, workflows, URL rendering, SDKs#4suyash-thakur wants to merge 12 commits into
suyash-thakur wants to merge 12 commits into
Conversation
An audit against the real backend (html-to-gif) found the docs
describing an API that does not exist, in three ways:
1. Key types: pk_live_/pk_test_ prefixes and a sandbox mode appear
nowhere in the product — a token is a bare 64-char hex string and
every key is live. Removed from 10 pages and both snippets; a
developer branching on key.startsWith('pk_') was going to break.
2. Error format: RFC 9457 Problem Details was documented (and even
claimed as shipped in the changelog) but the API returns plain
{ message } / { error } bodies, plus code on newer endpoints and
errors[] for compile failures. errors.mdx rewritten from reality,
with a tolerant reader snippet covering every real shape.
3. Rate limits: the per-plan RPM/RPD table and X-RateLimit-* /
Retry-After headers are fiction — the server never emits them.
Replaced with the truth: monthly credits (402) plus fixed
per-minute limits on a few public endpoints (429), no headers.
New coverage for the two products with none:
- api-reference/video.mdx — list/render/variables/preview, AI
generation, template management, the compile gate on tsx templates.
- api-reference/workflows.mdx — inbound hooks, the optional HMAC
signing scheme (verified against service/webhook-delivery.js:
t=...,v1=..., HMAC-SHA256 over "t.rawBody", 5-minute tolerance),
runs/stats, hook management.
Both added to the API Reference nav between Batch and Experiments.
…elog Clears the remaining high-damage gaps from the docs audit: - api-reference/url-rendering.mdx (new, in nav): GET /r/:uid.:format — the most embeddable feature had no page. Documents query-param variables, ?token= auth (an <img> tag cannot send headers), the transparent-pixel failure behaviour, 5-minute private caching, and a warning that a token-bearing URL is a credential. - Batch: the CSV input mode existed only in the dashboard docs; the batch page now shows both modes with the column→variable mappings. - MCP: pictify_screenshot never existed — screenshots ride on pictify_create_image's url argument, now documented truthfully. The server page gains the complete 31-tool table instead of naming 8. - Changelog: was frozen at January; August entry covers video templates, GIF output, AI generation, workflows and the playground.
Lands the in-progress work this branch carried uncommitted: the create endpoint now explains the engine field — Handlebars HTML templates (compile-validated on save, 422 with the reason on failure) versus FabricJS canvas JSON (the default, for editor exports) — with worked cURL examples for both, and the OpenAPI spec gains the matching request/response shapes.
.mcp.json points tooling at the hosted Mintlify docs MCP endpoint (no secrets); the plan doc archives the completed @pictify/mcp-server work under the repo's existing docs/plans convention.
From the docs PR #4 accuracy review — fixes to claims the backend contradicts, including two introduced by this branch's own corrections: - The 402/429 quota story was wrong for the flagship endpoints: image, GIF, HTML-template and batch return 429 with code "quota_exceeded" when monthly credits run out (verify_api_token/quota_guard); only the newer video/workflow routes return 402. The old advice ("on 429, back off and retry") sent out-of-credits users into a futile retry loop against a monthly limit. Four files now teach: check `code` first — quota_exceeded means credits, not rate. The no-rate-limit- headers claim is also scoped honestly: the fixed-rate public/preview endpoints DO send standard x-ratelimit-*/retry-after headers. - Batch CSV mappings direction was inverted ({csv_column: variable}); the backend reads {templateVariable: 'CSV Column'} — following the page produced 400 "No valid data after applying column mappings". - The openapi variable-type enum listed number/boolean/url/date (all rejected by the backend schema) and omitted chart/table; the flagship create example used type "boolean" and would fail validation. Enum and example now match models/Template.js exactly; pdfPreset gains A3_LANDSCAPE/CUSTOM. - Video page: variable validation described per kind (timeline validates VALUES, ignores unknown names by design; tsx passes through as props); GIF caps scoped to the timeline path (tsx encodes natively, half the composition fps, no width cap); preview marked tsx-only (timeline → 501); imports mention @remotion/*. - Workflows table: GET /workflow lists RUNS, not workflow objects. - dashboard/security key pages: the last test-key fabrications removed (100 renders/day, watermarks, "use test key"), broken /api-reference/keys link repointed at /authentication. - Go SDK examples take options by pointer, as the SDK requires.
Extends Rate Limits and Quotas rather than adding a nav page. Documents only verified behavior: every render costs 1 render credit (GIF URL capture 1.5), AI costs per util/ai-credits.js AI_COSTS, per-plan AI allowances per AI_LIMITS, and the billing rules (per user intention, failures never billed, silence never billed, internal renders included). Includes the 402 ai_quota_exceeded body.
The template-editor copilot now spends the same unified AI-credit pool as the video copilot (no separate per-plan copilot bucket, and background removal is not a sold feature). The Copilot row now names both surfaces, and the section states explicitly that there are no separate per-feature AI allowances.
Experiments feature retired July 2026. DB evidence (read-only check): experiments collection has 10 rows, 4 with status "running", but the newest updatedAt on ANY row is 2026-04-19 — over 3 months stale. Removed the Experiments nav group and concepts/guides entries from docs.json, api-reference/experiments.mdx, api-reference/endpoints/ experiments/ (9 pages), concepts/experiments.mdx, guides/ab-testing.mdx. openapi/v1.yaml: dropped /experiments/api* and /s/* paths, the Experiment* schema family (Experiment, ExperimentVariant, GoalConfig, BanditConfig, ConditionTree, VariantSchedule, ExperimentQuota, QuotaUsage, ExperimentEvent, ExperimentEventResponse), the writeKeyAuth security scheme, and the Experiments tag. mcp-server.mdx: removed the Experiments tool row and corrected the tool count 36 -> 26. Verified: docs.json parses; all 68 nav pages exist on disk; no dangling internal links to removed pages; openapi/v1.yaml parses (20 paths, 18 schemas).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Corrects the docs against the live API and covers the new surface: