Skip to main content
This page builds one API from a public URL, reads its contract and calls one endpoint, using only curl against https://api.peel.sh.

Prerequisites

Create an API key under API Keys in peel.sh settings, then export it:
Every request sends the key in the X-API-Key header. Peel is in private preview and accounts are by invitation. Join the waitlist to get one, or try a public API first with no account. See Plans and limits for build and run allowances and rate limits.

Build an API

POST /v1/apis queues a build. Send wait_for_completion: true to hold the request until the build finishes, fails or asks a question.
The response wraps the API record in api. Values below are illustrative and IDs are shortened; the field names are exact.
Save the ID:

Wait for the build

If you did not wait, or timed_out is true, poll GET /v1/apis/{api_id} every 2 to 5 seconds until api.status is completed or failed, or until api.user_input_prompt is not null.
To wait without polling, call GET /v1/apis/{api_id}/wait, which holds the request until the build finishes, fails or asks a question. To be told instead, subscribe a webhook to build.completed, build.failed and build.needs_input.

Inspect the contract

The same GET /v1/apis/{api_id} response lists the endpoints. Read it before calling anything.
Use these fields to make the next call:

Call an endpoint

POST /v1/apis/{api_id}/endpoints/{endpoint_name}:call runs the published program. The JSON body is the endpoint’s input.
Every call returns the same envelope. Values are illustrative.
Two response headers describe the call itself. Peel-Verified names the program that answered and when it last passed verification, as artifact=<sha256>; at=<ISO time>: the time is the version’s publication, or its latest passing repair check if that is later. Server-Timing splits the call’s time into pre, admit, run and settle in milliseconds; run includes the target site. Calling an endpoint name that does not exist returns 404 with an available_endpoints array. Calling before the API is completed returns 409 with the current status.

Answer a build question

A build can stop to ask you something, for example a clarification or a private value. There are two shapes, and api.user_input_prompt tells you which. Live question. api.status is running and api.user_input_prompt.live is true. The build keeps its browser and model history while it waits. Answer with exactly question_id and answer, both inside response:
An illustrative pending question on GET /v1/apis/{api_id}:
When secret is true, Peel keeps the answer on its server and only the name of the value reaches the build model. Any extra key in response returns 400 with Answer the live question with exactly question_id and answer. Paused build. api.user_input_prompt is set and describes what is missing, and response is a free-form object that answers it. The same route returns 409 when the API is not waiting for input. The response is the same envelope as a build, with response_queued: true in place of matched:

Common errors

The full catalog is in Errors.

Next steps