Skip to content
Speccy
Search
Ctrl
K
Cancel
GitHub
Select theme
Dark
Light
Auto
Menu
Tutorials
From a blank page to a build packet
Link an SDD to a PRD
How-to guides
Review docs you already have
Adopt a repo and decide in a pull request
Close a coverage gap
Link to an issue, a page or the code
Change a profile
Ask for and approve a waiver
Hand a spec to a coding agent
Verify a build
Keep the verdict in CI
Add a model backend
Run hosted mode
Concepts
The verdict
The review pipeline
Profiles and size
Waivers and the sidecar
Traceability
Handoffs and build reports
Guarantees
Reference
The TUI
.speccy.yaml
Frontmatter
Sidecar
Check catalog
CLI
Configuration
GitHub Action
MCP tools
Profile schema
Reply commands
HTTP API
Overview
Operations
Get the server version and mode.
GET
Who the caller is (SDD §3). Anonymous callers get signed_in false.
GET
Look up a share link (REQ-085). A revoked or expired link is not found.
GET
Enter a share link as a guest with a display name (REQ-086). Sets the guest cookie.
POST
Who can see the bundle, and its share link state (REQ-084, REQ-085).
GET
Report what the build learned about the doc (REQ-137). A blocked report opens a blocking thread.
POST
The handoffs of a bundle, newest first (REQ-136).
GET
Take the build packet of a Build Ready bundle, and record the handoff (REQ-136).
POST
Take the build packet as a .zip file, and record the handoff. The .zip holds the files that speccy handoff --out writes.
POST
Ask to excuse one trace ID in one code repo. It never goes in the doc's sidecar.
POST
What the Delete control offers for this bundle, by the kind of source that makes it.
GET
The verification runs of a bundle, newest first.
GET
Queue a verification of one build of this bundle against a code repo at one commit, or a folder.
POST
Say which repo and commit, or which folder, a pasted target names, before a run starts.
POST
The targets that prefill the verify field. The implemented-by links first, else the repo of the last run.
GET
Follow a verification run's progress by trace ID, as server-sent events.
GET
One verification run with the outcome of each trace ID.
GET
Write the type and the size that the review used into the main doc's frontmatter (REQ-135).
POST
Change the profile of the bundle's main doc.
PUT
Set the visibility of the bundle (REQ-084). Leaving link visibility revokes the share link.
PUT
Make a new share link (REQ-085). It replaces the old one and sets link visibility. The URL appears one time.
POST
Revoke the share link (REQ-085).
DELETE
List invite links, newest first (REQ-081).
GET
Make a single-use invite link with a role (REQ-081). The URL appears one time.
POST
Revoke an unused invite link.
POST
Make a one-time password reset link for a user (REQ-082). The URL appears one time.
POST
The workspace settings (REQ-009, REQ-081, REQ-105).
GET
Change the workspace settings.
PUT
List bundles, and the folders that look like bundles but are not valid.
GET
Create a bundle from a profile's template (REQ-016).
POST
Import a bundle from a .md file, a .zip file, or pasted markdown.
POST
List the markdown files of an import, with the profile of each and the links Speccy offers.
POST
Get one bundle with its spec docs.
GET
Delete a bundle whose text Speccy holds, with everything that hangs off it. Permanent.
DELETE
Get one spec doc.
GET
List the files of a bundle version. The default is the current version.
GET
Delete a file. Creates a version (REQ-005).
DELETE
Get the bytes of one file in a bundle version. The default is the current version.
GET
Create or replace a file. Creates a version when the content changed (REQ-005).
PUT
Rename or move a file inside the bundle. Creates a version (REQ-005).
POST
List the versions of a bundle, newest first.
GET
Compare two versions of a bundle, by file and by section of the main doc (REQ-006).
GET
Download a bundle version as a .zip file, or the current version as a self-contained HTML report with the verdict (REQ-008).
GET
List the review runs of a bundle, newest first.
GET
Start a full review of the current version (REQ-020). Lint runs on its own on every save.
POST
Review bundle files that are not saved on the server (SDD §12.2 --server, REQ-111 review_content). The server keeps the files and the result for 90 days for the report (SDD §12.4); it changes no bundle.
POST
The self-contained HTML report of a review from POST /reviews (SDD §12.4).
GET
Estimate the tokens and cost of a full review before it starts (REQ-104).
GET
List the sentences of the current main doc that start with "Assumption:" (REQ-033).
GET
The bundle's links, its traceability matrices, and suggested trace IDs (REQ-050, REQ-052, REQ-058).
GET
Remove one outgoing link that Speccy holds for the doc.
DELETE
Insert suggested trace IDs into the main doc (REQ-052). Speccy changes the doc only on this request.
POST
Answer a coverage gap with "This doc covers it". Speccy adds "Covers <ID>." at the end of the section as a new version.
POST
Follow a run's progress by stage, as server-sent events (REQ-026).
GET
List a run's factual claims and their labels (REQ-031).
GET
List a run's build questions, reader answers, and results (REQ-040 to REQ-046).
GET
List the MCP connections (REQ-112).
GET
Add an MCP connection.
POST
Change an MCP connection. Leave the secret out to keep the stored one.
PUT
Delete an MCP connection.
DELETE
Connect and list the server's tools, to choose the allowlist.
GET
Get one review run and its verdict.
GET
The ordered points of the bundle's current review that need a human decision (SDD §13.3).
GET
Summarize what changed in meaning between two versions, and the change in findings (REQ-007).
POST
The run report (SDD §13.1): stage timings, reader diversity, and findings by category.
GET
Ask the AI for a patch that fixes one finding (REQ-025). The doc does not change.
POST
Apply the finding's suggested patch to the current version as a new version (REQ-025). Speccy changes the doc only on this request.
POST
List the findings of a run, in document order.
GET
The markdown files the local scan passed over because they name no type (REQ-001). Empty in hosted mode.
GET
Write a type into skipped files, so they become spec docs (REQ-001). One request takes every picked doc, so the order of the picks does not matter (#73).
POST
The links Speccy offers between docs in one folder, for a person to confirm.
POST
The profile that fits a markdown doc, from its headings (REQ-008).
POST
List the threads of a bundle, open first (REQ-087).
GET
Open a thread on a bundle, anchored to text, a section, or a finding (REQ-087). A guest opens threads for humans only.
POST
A thread with its messages.
GET
Post a message. In a thread for the AI, the AI answers with sources (REQ-088).
POST
Mark a message as the thread's decision. A later decision is recorded as a reversal (REQ-089).
POST
Mark the thread blocking or not. An open blocking thread prevents Build Ready (REQ-089).
PUT
Resolve or reopen the thread.
PUT
List the waivers of a bundle (REQ-072 to REQ-074).
GET
Request a waiver for one finding, with a reason of at least 20 characters (REQ-072).
POST
Withdraw one acknowledgement of the doc, a trace entry or standalone. It takes effect at once, with no approval.
POST
Approve a waiver under the profile's policy (REQ-073, §9.1). A final approval writes it to the doc's sidecar (DEC-009).
POST
Reject a waiver, with a decision reason the requester reads.
POST
The review status of a bundle (§9.5).
GET
Ask for a review and assign reviewers (REQ-090). A draft moves to in review.
POST
Approve the current version (REQ-076). The author cannot approve. Approval needs a current Build Ready verdict.
POST
The members of the workspace, for reviewers and mentions. Empty in local mode.
GET
The caller's inbox (REQ-091).
GET
Mark the inbox as read up to now.
POST
Mark one inbox item read.
POST
The metrics of SDD §8.9, per profile (REQ-092). Maintainers and admins.
GET
A profile with its YAML, template, versions, and maintainers (REQ-013).
GET
Save a profile as a new version (REQ-012, REQ-013). Maintainers of the profile and admins.
PUT
Delete a profile. Admins only. Refused for a built-in, and while a bundle names its key.
DELETE
Set the maintainers of a profile. Admins only.
PUT
The YAML diff and the template diff between two versions of a profile.
GET
Write a new version whose text equals an earlier one. No number changes meaning.
POST
The suggestions for a profile, as threads on its checks (REQ-015).
GET
Suggest a change to a check, the template, or a limit (REQ-015).
POST
List the profiles, with their current versions.
GET
Create a profile for a new doc type. Admins only.
POST
List the model backends. Secrets show their last 4 characters only (SDD §14.1).
GET
Add a model backend (REQ-100).
POST
Change a backend. Leave the secret out to keep the stored one.
PUT
Delete a backend that no role uses.
DELETE
Send one short call to a backend and model, to check the setup.
POST
List the agent CLI presets and whether each CLI is installed (REQ-102).
GET
List the roles and their backend and model (REQ-101).
GET
Assign a backend and model to a role.
PUT
Remove a role's assignment.
DELETE
The GitHub token of the workspace (DEC-019). The token itself is never returned.
GET
Set the fine-grained personal access token that reads repos and opens pull requests.
PUT
Remove the GitHub token. The GitHub sources stop syncing.
DELETE
The GitHub repos, branches, and folders that Speccy reads bundles from (REQ-123).
GET
Make a source from a source URL, and keep its bundles in step (REQ-123, REQ-128).
POST
Read a source URL and say what it names, before the source is made (REQ-128).
POST
Stop reading a source. Its bundles are archived; their reviews and threads stay.
DELETE
The markdown files a person marked as not a spec (REQ-133).
GET
Mark a markdown file as not a spec, so Speccy stops offering to adopt it (REQ-133).
POST
Take the mark off a file, so it appears again (REQ-133).
DELETE
The markdown files under the source that the scan passed over, with a guessed doc type each (REQ-133).
GET
Accept a doc type for skipped docs of the source, held in Speccy (REQ-133). The repo takes no commit.
POST
Open a pull request that writes the accepted types into the repo's .speccy.yaml (REQ-133).
POST
Read the source's branch now.
POST
Publish the draft of a GitHub bundle as a branch, a commit, and a pull request (REQ-123).
POST
Drop the draft of a GitHub bundle. The version from GitHub becomes current again.
POST
Get this month's token budget and use (REQ-104).
GET
Set the monthly token limit. No limit means no budget.
PUT
Render markdown to HTML. Each block carries its source position (DEC-017).
POST
Operations
Back up and restore
Upgrade
The master key
Budget and model cost
GitHub
Select theme
Dark
Light
Auto
Overview
Speccy API
0.1.0
Section titled “Speccy API 0.1.0”
Information
License: AGPL-3.0-only
OpenAPI version:
3.1.0
Operations
Section titled “ Operations ”
GET
/meta
GET
/me
GET
/share/{token}
POST
/share/{token}
GET
/bundles/{bundleId}/access
POST
/handoffs/{handoffId}/report
GET
/docs/{docId}/handoff
POST
/docs/{docId}/handoff
POST
/docs/{docId}/handoff/zip
POST
/docs/{docId}/verification-waivers
GET
/bundles/{bundleId}/delete-plan
GET
/docs/{docId}/verifications
POST
/docs/{docId}/verifications
POST
/docs/{docId}/verifications/resolve
GET
/docs/{docId}/verifications/defaults
GET
/verifications/{runId}/events
GET
/verifications/{runId}
POST
/docs/{docId}/adopt
PUT
/docs/{docId}/profile
PUT
/bundles/{bundleId}/visibility
POST
/bundles/{bundleId}/share
DELETE
/bundles/{bundleId}/share
GET
/admin/invites
POST
/admin/invites
POST
/admin/invites/{inviteId}/revoke
POST
/admin/reset-links
GET
/admin/settings
PUT
/admin/settings
GET
/bundles
POST
/bundles
POST
/bundles/import
POST
/bundles/import/preview
GET
/bundles/{bundleId}
DELETE
/bundles/{bundleId}
GET
/docs/{docId}
GET
/docs/{docId}/files
DELETE
/docs/{docId}/files
GET
/docs/{docId}/files/content
PUT
/docs/{docId}/files/content
POST
/docs/{docId}/files/rename
GET
/docs/{docId}/versions
GET
/docs/{docId}/diff
GET
/docs/{docId}/export
GET
/docs/{docId}/runs
POST
/docs/{docId}/runs
POST
/reviews
GET
/reviews/{reviewId}/report
GET
/docs/{docId}/runs/estimate
GET
/docs/{docId}/assumptions
GET
/docs/{docId}/trace
DELETE
/docs/{docId}/links
POST
/docs/{docId}/trace/ids
POST
/docs/{docId}/trace/cover
GET
/runs/{runId}/events
GET
/runs/{runId}/claims
GET
/runs/{runId}/questions
GET
/admin/mcp
POST
/admin/mcp
PUT
/admin/mcp/{connectionId}
DELETE
/admin/mcp/{connectionId}
GET
/admin/mcp/{connectionId}/tools
GET
/runs/{runId}
GET
/docs/{docId}/tour
POST
/docs/{docId}/diff/summary
GET
/runs/{runId}/report
POST
/runs/{runId}/findings/{findingId}/fix
POST
/runs/{runId}/findings/{findingId}/fix/accept
GET
/runs/{runId}/findings
GET
/skipped
POST
/skipped
POST
/links/suggest
POST
/profiles/guess
GET
/docs/{docId}/threads
POST
/docs/{docId}/threads
GET
/threads/{threadId}
POST
/threads/{threadId}/messages
POST
/threads/{threadId}/decision
PUT
/threads/{threadId}/blocking
PUT
/threads/{threadId}/status
GET
/docs/{docId}/waivers
POST
/docs/{docId}/waivers
POST
/docs/{docId}/acknowledgements/withdraw
POST
/waivers/{waiverId}/approve
POST
/waivers/{waiverId}/reject
GET
/docs/{docId}/status
POST
/docs/{docId}/review-request
POST
/docs/{docId}/approve
GET
/people
GET
/inbox
POST
/inbox/seen
POST
/inbox/read
GET
/insights
GET
/profiles/{key}
PUT
/profiles/{key}
DELETE
/profiles/{key}
PUT
/profiles/{key}/maintainers
GET
/profiles/{key}/diff
POST
/profiles/{key}/rollback
GET
/profiles/{key}/threads
POST
/profiles/{key}/threads
GET
/profiles
POST
/profiles
GET
/admin/backends
POST
/admin/backends
PUT
/admin/backends/{backendId}
DELETE
/admin/backends/{backendId}
POST
/admin/backends/{backendId}/test
GET
/admin/presets
GET
/admin/roles
PUT
/admin/roles/{role}
DELETE
/admin/roles/{role}
GET
/admin/github
PUT
/admin/github
DELETE
/admin/github
GET
/github/sources
POST
/github/sources
POST
/github/resolve
DELETE
/github/sources/{sourceId}
GET
/dismissed-docs
POST
/dismissed-docs
DELETE
/dismissed-docs
GET
/github/sources/{sourceId}/skipped
POST
/github/sources/{sourceId}/skipped
POST
/github/sources/{sourceId}/mapping
POST
/github/sources/{sourceId}/sync
POST
/docs/{docId}/publish
POST
/docs/{docId}/draft/discard
GET
/admin/budget
PUT
/admin/budget
POST
/render