API Updates

Use this page when an API already exists and you need to decide the next operation. If you are operating through the CLI instead of raw HTTP, the equivalent commands are:

peel apis get <api-id>
peel apis health <api-id>
peel respond <api-id> --body '{"field":"value"}'
peel revise <api-id> --instructions "..."
peel rebuild <api-id>

Quick choice

Choose revise when the website is still the right target and you need to change the build instructions, such as missing fields, extra fields, the wrong focus, or a tighter schema.
Choose rebuild when the website changed, runtime health recommends it, or endpoint calls now fail broadly.
Choose respond when the API is paused in needs_input.

What each operation does

GET /v1/apis/{api_id}
- Returns the current API record.
- Use it to inspect status, endpoints, endpoint runtime_policy and runtime_verification, failure, failure_reason_code, and user_input_prompt.
GET /v1/apis/{api_id}/health
- Returns binding-level runtime health when an API is published, or build-stage health when it has not published a binding yet.
- Use it to inspect status, task_status, detail, recommended_action, failure, counters, timestamps, and per-endpoint health.
POST /v1/apis/{api_id}/respond
- Sends a response only when the API status is needs_input.
- Optional body flags: wait_for_completion, timeout_ms.
POST /v1/apis/{api_id}/revise
- Queues a revision with new instructions.
- Use it when the target is still right but the build intent needs to change.
POST /v1/apis/{api_id}/rebuild
- Queues a fresh rebuild from the same binding.
- Use it when the underlying site or request surface likely changed.

{
  "api": {
    "id": "4d0d8c18-3a06-4d53-9a57-2e5aa3f8c0cc",
    "status": "completed",
    "endpoint_count": 3,
    "failure": null,
    "failure_reason_code": null
  }
}

The API id is the durable identity. Endpoint names and schemas can change after a successful revise or rebuild, so re-inspect the API before calling an updated endpoint.

Decision rules

Symptom	Right move	Reason
`status: "needs_input"` with a `user_input_prompt`	`respond`	The build is paused and waiting for input.
API is `completed` but the shape is wrong	`revise`	The target is right, but the build intent is wrong.
Published API health returns `recommended_action: "rebuild"`	`rebuild`	Runtime indicates the published binding is stale or unhealthy.
Build-stage health returns `status: "build_failed"`	Follow `failure.recommended_action`	No binding was published yet, so inspect the structured failure before choosing revise, retry, or support.
Endpoint calls started failing broadly on a previously healthy API	`health`, then likely `rebuild`	Check health before assuming site change.
Instructions are clearly wrong but the site still works	`revise`	Do not rebuild on the same instructions.

Status handling

Status	What it means	Next action
`queued` / `running`	Build is in progress.	Wait. Do not revise or rebuild yet.
`needs_input`	Build paused; `user_input_prompt` describes what it needs.	`respond` with the requested payload. A `respond` call outside this state returns `409`.
`completed`	Contract is published and callable.	Safe point for `revise`, `health`, and endpoint calls.
`failed`	Build did not complete. Check `failure_reason_code`, `failure.non_publishable_reason`, and `failure.artifact`.	Follow `failure.artifact.suggested_user_action`. Build failure classes and examples are documented in Errors.

If runtime calls are failing on a previously healthy endpoint, the runtime error_code catalog in Errors helps you decide between retry, rebuild, and revise.

Health semantics

GET /v1/apis/{api_id}/health returns one of three health shapes. For a published API, it returns binding-level runtime health:

{
  "binding_id": "binding_abc",
  "version_id": "version_xyz",
  "status": "degraded",
  "recommended_action": "rebuild",
  "success_count": 18,
  "error_count": 6,
  "timeout_count": 2,
  "last_success_at": "2026-04-01T10:00:00.000Z",
  "last_failure_at": "2026-04-01T10:12:00.000Z",
  "quality_score": 0.71,
  "endpoints": []
}

For an API that exists but has not published a binding, it returns build-stage health:

{
  "binding_id": null,
  "version_id": null,
  "status": "pending_build",
  "task_status": "running",
  "detail": "API build has not produced a binding yet",
  "recommended_action": "none",
  "success_count": 0,
  "error_count": 0,
  "timeout_count": 0,
  "last_success_at": null,
  "last_failure_at": null,
  "quality_score": null,
  "endpoints": []
}

If the build failed before publishing, the same route returns status: "build_failed", task_status: "failed", failure_reason_code, a detail string with the build failure context, a top-level recommended_action copied from the structured failure, and the same structured failure object exposed by GET /v1/apis/{api_id}.

Health signal	What it means	Next action
`status: "pending_build"`	The API exists, but no binding is published yet.	Wait, or inspect `GET /v1/apis/{api_id}` if `task_status` is `needs_input`.
`status: "build_failed"`	The build failed before publishing a callable binding.	Inspect `failure` on the health or API detail response and follow `failure.artifact.suggested_user_action`.
`status: "healthy"`, `recommended_action: "none"`	Recent calls are succeeding.	No action needed.
`status: "degraded"`	Mixed success and failure in the window.	Check which endpoints are failing in `endpoints[]` before choosing rebuild or revise.
`status: "needs_rebuild"` or `recommended_action: "rebuild"`	Failure rate or quality score crossed the rebuild threshold.	Prefer `rebuild` over `revise` unless your instructions are clearly wrong.

Re-validate after any update

Call the same endpoint name again after respond, revise, or rebuild.

curl -X POST "$PEEL_API_BASE/v1/apis/$API_ID/endpoints/get_top_stories:call" \
  -H "X-API-Key: $PEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":10}'

Re-check:

api.status
api.failure
endpoint list
one or two critical runtime calls

If the endpoint contract changed unexpectedly, stop and inspect before widening usage. CLI equivalents:

peel apis get <api-id>
peel call <api-id> <endpoint_name> --params '{"key":"value"}'

Get started

Concepts

How-tos

Reference

API Updates

Quick choice

What each operation does

Decision rules

Status handling

Health semantics

Re-validate after any update

​Quick choice

​What each operation does

​Decision rules

​Status handling

​Health semantics

​Re-validate after any update

Quick choice

What each operation does

Decision rules

Status handling

Health semantics

Re-validate after any update