docs(api): live OpenAPI specs as source of truth + webhook truth fixes#79
Open
johnxie wants to merge 1 commit into
Open
docs(api): live OpenAPI specs as source of truth + webhook truth fixes#79johnxie wants to merge 1 commit into
johnxie wants to merge 1 commit into
Conversation
- developer-home: link the live v1/v2 OpenAPI specs as the source of truth, add
an Errors section documenting the typed {ok,code,message} envelope (taskcade #26936)
- webhooks: correct the stale 'no subscription endpoint' note — document the new
POST /api/v2/subscribeWebhook + unsubscribeWebhook (Beta, Pro+), and make the
Pro+ gating explicit (taskcade #26713)
- llms.txt: surface the live v1/v2 specs + v2 reference + SDK + webhooks for LLM consumers
- api-v2-reference: drop the hardcoded 'openapi 0.1.0' (the live spec owns the version)
- retire the orphaned root 'Real API.json' (stale v1 snapshot, 42 paths vs 49 live;
not referenced by any page — the embedded specs live under .gitbook/assets/)
Handwritten reference pages kept as companion guides; the live spec is authoritative.
Note: taskcade #26919 (90d /api login-JWT + refresh) needs no doc change — the public
docs cover PAT + OAuth2 (both already accurate) and never document the legacy /api/login flow.
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.
Summary
Make the live OpenAPI specs authoritative and fix stale/inaccurate API statements. Handwritten reference pages stay as companion guides (examples, patterns) — they just now point at the live spec as the source of truth.
Crosslinks (spec = source of truth)
taskade.com/api/documentation/v1+/v2(and/json), framed as the source of truth vs the hand-written companions./api/v1).Truth fixes
POST /api/v2/webhookssubscription endpoint." That is no longer true — documents the newPOST /api/v2/subscribeWebhook+unsubscribeWebhook(Beta, account-level,task.duetoday) and makes the Pro+ gating explicit (taskcade #26713). Pairs with taskcade #26765.{ ok, code, message }envelope (taskcade #26936) so callers branch oncode, not bare 500s.openapi 0.1.0string — the live spec owns the version.Cleanup
Real API.json— a stale v1 snapshot (42 paths vs 49 live) not referenced by any page. The embedded specs that power{% openapi %}blocks live under.gitbook/assets/and are untouched.Intentionally not changed
/api/loginJWT (90d +POST /api/refresh), which the public docs never document. The documented surfaces — Personal Access Tokens and OAuth 2.0 (1h + refresh) — are already accurate, so no edit was made rather than inject a misleading claim.Follow-ups (not in this PR)
{% openapi %}block (the v1 guide already does this against.gitbook/assets/); needs a committed/synced v2 spec file + per-operation blocks.