health, respond, revise and rebuild. All four keep the same api.id.
Choose an operation
Do not rebuild when your instructions are wrong, and do not revise when the site changed. Check health first. Both
revise and rebuild count against the build rate limit and the build-queue limit; see Plans and limits.
Check health
status.
Published API. Health for the live version:
status is pending_build, build_status is queued or running, and version_id is null.
Build failed. status is build_failed, build_status is failed, and the response carries a detail string and the same structured failure object as GET /v1/apis/{api_id}. recommended_action is copied from failure.
For a failed build,
recommended_action is one of contact_support, revise_task, retry_later, try_different_url or wait_or_rebuild.
Revise an API
POST /v1/apis/{api_id}/revise keeps the site and rebuilds against new instructions (1 to 2000 characters). It counts as one build; not counted if the revision fails.
{ "revision_queued": true, "waited": true, "timed_out": false, "api": { ... } }. The optional wait_for_completion and timeout_ms (1000 to 300000) work as they do on build.
Rebuild an API
POST /v1/apis/{api_id}/rebuild keeps the instructions and recompiles from fresh evidence. It counts as one build; not counted if the rebuild fails. The only field is an optional reason (1 to 500 characters), and the call never waits.
{ "rebuild_queued": true, "api": { "id": "...", "status": "queued", ... } }. Poll GET /v1/apis/{api_id} until status is completed.
Try a change as a draft
Add"draft": true to revise or rebuild. The build runs and is checked as usual, but its version is only stored: the current version keeps serving every call until you publish the draft. A draft costs one build like any other.
draft: true and a version_id. Call the draft by sending that id in the Peel-Version header; over MCP, pass it as version_id to call_endpoint or call_endpoint_batch.
Peel-Version returns 400 with code: "version_invalid", and a version of another API returns 404 with code: "version_not_found". Marketplace calls always run the current version. To publish the draft, roll back to its version_id. A rebuild draft needs a published version first; without one it returns 409 with code: "revision_source_missing".
Read the code
GET /v1/apis/{api_id}/code returns the program each endpoint runs. Without version_id it reads the current version; with it, any version from the revisions list, drafts included.
{ "api_id": "...", "version_id": "...", "current": false, "operations": [{ "name": "list_stories", "program": "..." }] }. In the app, open Versions on the API page and choose Code. The code is read-only. To change it, describe the change with revise as a draft, so Peel checks the new program against the live site before anyone calls it.
Read the page a version was built from
When a build publishes a version, Peel fetches the source URL once more, right after the build finishes, and keeps one record of what came back: the URL with query values and token-like path segments removed, the time, the status, the media type, a SHA-256 of the full body, a few response headers and the body itself, cut at 2 MB. Peel removes sign-in values, cookies, Authorization and tokens before it encrypts the copy. This is a fresh fetch, not the exact response the builder saw, so the site may have changed in between, or a plain fetch may get a different page than the browser did. Compare the copy with today’s page when an endpoint breaks.kept. With "sealed", download_url fetches the stored body for five minutes. With "hash_only", Peel kept the hash and the details but not the body, and reason says why:
sha256 is absent when the body was larger than 64 MiB. This route takes an API key only. Only the API’s owner can read its copies; anyone else gets 404 page_copy_not_found. Peel keeps one record per version and deletes it with the version.
Peel removes the private values it knows about: sign-in values, cookies and headers from the fetch, and tokens in the URL. A token that appears only inside the page’s HTML, such as one a site prints into a script, is not recognized and stays in the stored body. A short numeric code in the path, such as /preview/482913, is not recognized either and stays in the stored URL, and the copy is kept. The copy is encrypted and only you can read it, and the URL is the one you gave Peel. Do not build from a page that prints a private token for anyone who opens it.
List revisions
{ "api_id": "...", "builds": [ ... ] }. Each build has id, kind (build, rebuild, revision or repair), status, created_at, updated_at, completed_at, user_input_prompt, progress, failure, version_id, the version it published or stored, and draft, true when the version was stored without being made current.
The list holds only the newest builds. To read an older one, or to follow a build you started after later revisions, pass its id: GET /v1/apis/{api_id}/revisions?build_id=$BUILD_ID answers with builds holding only that build, or empty when it is not a build of this API.
Roll back
POST /v1/apis/{api_id}/rollback makes a version from the revisions list current: an earlier one, or a draft you want to publish. Pass its version_id.
{ "api": { ... }, "rolled_back": true }. A version_id that is not in this API’s history returns 404 with code: "version_not_found".
Automatic repair
PUT /v1/apis/{api_id}/repair with {"enabled": true} turns on automatic repair. While it is on, Peel re-runs the saved examples of the current version every day, and rebuilds the API with the same instructions after two failed checks. Repairs do not count against your builds. Send {"enabled": false} to turn it off.
A failing call counts as one of those checks. When a call fails because the site changed (upstream_error, invalid_upstream_json, output_schema_mismatch or program_failed), Peel re-runs the saved examples within minutes. If they fail too, the repair starts at once. A failure caused by your input, a timeout or a cancelled call never counts. Peel checks an API at most once an hour this way, and repairs it at most once a week.
While a repair runs, a call that fails the same way answers 503 with error_code: "api_repairing", retry_safe: true, the time the repair started and Retry-After. Calls that still work keep working on the current version. An execution job on a read endpoint waits for the repair and runs once more on the repaired API; if the repair fails, the job ends with api_repairing. Peel never reruns a write.
Webhooks send api.repairing when a repair starts, then api.repaired or api.repair_failed.
After any update
Endpoint names and schemas can change after a revise or rebuild. Re-readGET /v1/apis/{api_id}, then call one or two critical endpoints before widening usage. Calls that run while a rebuild is in progress use the previously published version; a new version replaces it only after it passes verification.