> ## Documentation Index > Fetch the complete documentation index at: https://docs.peel.sh/llms.txt > Use this file to discover all available pages before exploring further. # API Updates > Use health, respond, revise, and rebuild when an API drifts or stalls. 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: ```bash theme={null} peel apis get peel apis health peel respond --body '{"field":"value"}' peel revise --instructions "..." peel rebuild ``` ## 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. ```json theme={null} { "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](/reference/errors#build-failures). | If runtime calls are failing on a previously healthy endpoint, the runtime `error_code` catalog in [Errors](/reference/errors#runtime-error-codes) 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: ```json theme={null} { "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: ```json theme={null} { "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`. ```bash theme={null} 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: ```bash theme={null} peel apis get peel call --params '{"key":"value"}' ```