Skip to main content
Most of the docs reduce to six ideas: the build input, the evidence-backed lifecycle, the endpoint contract, the deterministic runtime boundary, the auth boundary, and the update model.

​
You give Peel a URL and instructions

A build starts with a single POST /v1/apis call: 
{
  "url": "https://news.ycombinator.com",
  "instructions": "Get top stories with title, score, and author"
}
url is the source. instructions describe the API surface you want. The same build record later drives every public adapter: REST, MCP, CLI, and exported OpenAPI. Build time is where Peel does the hard work. It can inspect pages, network traffic, selectors, and official public surfaces before deciding what can become a stable API. Runtime is intentionally narrower: it executes only the endpoint contract that was published.

​
A build moves through a lifecycle

Every API has a status that tells you whether it is callable yet:
StatusMeaning
queuedThe build is accepted and waiting to run.
runningThe build is in progress.
needs_inputThe build paused. Send the requested payload through POST /v1/apis/{api_id}/respond.
completedThe contract passed publication gates and is callable.
failedPeel did not publish an API. Inspect failure_reason_code, failure.non_publishable_reason, and failure.artifact before deciding whether to revise or rebuild.
matched: true on the create response means Peel reused an existing compatible API instead of starting a new build.

​
Endpoints publish a contract

A completed API exposes one or more endpoints under api.endpoints. Each entry gives you the endpoint name, schemas, auth requirement, compiled target method, and often runtime policy or verification diagnostics. Treat that contract as the source of truth for payloads and target behavior across every public surface. For the full field list, see How it works. The runtime route is always: 
POST /v1/apis/{api_id}/endpoints/{endpoint_name}:call
Runtime calls do not launch browsers or call models. If the site changed enough that the stored contract no longer works, use health diagnostics and rebuild to compile from fresh evidence.

​
The auth boundary is per endpoint

Every endpoint declares an auth_requirement:
  • public: call it directly with your Peel X-API-Key.
  • session_required: call the API’s login endpoint first, then pass session_id and encryption_key on later calls.
That field is the authoritative signal. The API-level auth_mode, auth, and requires_session fields summarize the API as a whole, but the per-endpoint requirement is what you check before each call. Host auth is covered in Authentication. The compiled family view (api.auth) is documented in Authenticated APIs.

​
You update an API with revise or rebuild

Once an API exists, you have two ways to change it:
  • revise: keep the same source URL, change the instructions. Use when the target is right but the build intent needs to change. Billed whether or not the revision succeeds.
  • rebuild: keep the same instructions, refresh the build evidence. Use when the site changed or runtime health recommends it. Not charged directly; runtime calls on the rebuilt contract are charged normally.
Both keep the same api.id, so existing callers do not need to migrate. The decision rules are in API updates. Per-operation costs are in Credits and limits.