Skip to main content
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

SymptomRight moveReason
status: "needs_input" with a user_input_promptrespondThe build is paused and waiting for input.
API is completed but the shape is wrongreviseThe target is right, but the build intent is wrong.
Published API health returns recommended_action: "rebuild"rebuildRuntime indicates the published binding is stale or unhealthy.
Build-stage health returns status: "build_failed"Follow failure.recommended_actionNo binding was published yet, so inspect the structured failure before choosing revise, retry, or support.
Endpoint calls started failing broadly on a previously healthy APIhealth, then likely rebuildCheck health before assuming site change.
Instructions are clearly wrong but the site still worksreviseDo not rebuild on the same instructions.

​
Status handling

StatusWhat it meansNext action
queued / runningBuild is in progress.Wait. Do not revise or rebuild yet.
needs_inputBuild paused; user_input_prompt describes what it needs.respond with the requested payload. A respond call outside this state returns 409.
completedContract is published and callable.Safe point for revise, health, and endpoint calls.
failedBuild 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 signalWhat it meansNext 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"}'