Skip to main content
Endpoints that sign in to a site or change something on it follow stricter rules: secrets stay on the host, writes need exact confirmation, and an uncertain write is never repeated.
Status: preview. Saved logins (the Logins page in the app), authenticator codes, and build questions for codes sent by text or email are deployed. Builds that sign in have passed end to end through api.peel.sh on nine self-hosted apps so far: Redmine, MantisBT, Paperless-ngx, Moodle, Dolibarr, osTicket, Koha, vtiger and SENAITE. Others we tried did not pass, so coverage is still partial. This page documents the contract the API schemas and exports describe. Do not depend on signed-in endpoints in production until this note changes.

Saved logins

The Logins page keeps one login per site: a username, a password, any extra details the site asks for, and how it sends two-factor codes. Values are encrypted and never shown again. Saving, changing or removing a login needs a signed-in browser session, not an API key. On a team, admins and members use and change the account’s saved logins; tool users run endpoints with them but cannot see them. To bring logins from a password manager, choose Import and pick its CSV export. Peel reads columns named url (or login_uri, website) and username (or login_username, email), plus password and an authenticator column (otpauth, totp, login_totp) when present. The file is read in your browser, and only the logins you pick are sent, one per site.

Private inputs

A call supplies private values in runtime_inputs, a sibling of the normal parameters in the request body. Put runtime_inputs and action_confirmation in the same object as the parameters: either the whole body, or the params object if you use one. The endpoint asks for each value by name, and the host fills it only on the exact site it was given for. Values, and the one-time codes made from them, never enter model prompts, generated code or saved programs. For totp, secret is a Base32 seed, origin is one exact http or https origin, algorithm is SHA-1, SHA-256 or SHA-512 (default SHA-1), digits is 6 or 8 (default 6) and period is 15 to 120 seconds (default 30). A name cannot be both a static secret and a totp entry. Peel refuses to fill a secret if the actual form or its destination is on a different origin than the one you supplied it for, and it asks for no substitute value.

Sign in and reuse the session

A login endpoint has endpoint_type: "login". Protected endpoints have auth_requirement: "session_required" and need the session it returns on every call. Start the login as an execution job. Peel asks for each credential, then asks you to approve the exact sign-in request. Nothing is sent to the site until you approve.
Read the job with GET /v1/executions/{id}. While state is needs_input, answer question with POST /v1/executions/{id}/input: When state is succeeded, result.data holds session_id and encryption_key. Send both values as headers on later calls:
Over MCP, pass session_id and encryption_key as top-level call_endpoint arguments, next to api_id and endpoint_name, not inside params. The session is bound to your account and the API, and it expires. If a protected call omits either value, Peel returns 400 with code: "missing_session_credentials" before contacting the site.

When the session expires

When a read’s session is gone (session_not_found) or the site no longer accepts it (access_session_expired), and a saved login on the Logins page covers the site, Peel signs in once with that login and runs the read again. The answer then carries session_renewed: true and a new session_id and encryption_key. Send the new pair from then on: the old one no longer works. The sign-in is charged as a call to the login endpoint. Peel does not sign in again for writes, for saved logins that ask for an emailed or texted code, or while another automatic sign-in to the same API is running. Those calls return the original error.

Reads that need a POST

A signed-in read sends GET and HEAD requests, GraphQL queries and a few known search requests. Some sites load their rows with other POST requests. When a build needs one, it asks you to approve that exact path. Peel cannot prove such a request changes nothing, so approve it only if it just loads data. Approved paths are saved with the API and run on every call. A new build asks again.

Confirm a write

A write runs only after you confirm it. Confirmation binds the exact artifact, operation, business input and outbound requests, so a model label or a structural check cannot grant authority. Send it as action_confirmation: Peel records a durable claim before it sends anything. Confirming the same action twice returns the first recorded result and sends nothing again. A change to the input, the grants or the credentials under an existing key is a conflict, not a replay. Peel never repeats a write whose outcome it cannot confirm, and it never infers success from an HTTP 200. A write is published only after a real example run proved its postconditions, so a successful result means Peel observed the effect it declared.

Read the outcome of a write

Write results include action_outcome and retry_safe. A failed call also carries retry, which says how it may be sent again. See Repeating a failed call.

Run an interactive execution

When an endpoint needs a named value while it runs, such as a one-time code or a dialog decision, start an execution job instead of a single call. The job keeps its browser on one host while you answer, and idempotency_key makes the start safe to repeat.
The response is 202 with a job:
state is running, needs_input, succeeded, failed, cancelled or unknown. An answer must name the pending question_id, so a stale answer cannot satisfy a later question. A secret answer is used once and removed. If Peel loses the host before it can confirm the outcome, the job ends as unknown and is never restarted automatically. Files for uploads and downloads use POST /v1/files, GET /v1/files/{fileId} and DELETE /v1/files/{fileId}, within the file limits.

Errors and what to do

See Errors for the full catalog.