> ## 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.

# Deterministic Runtime

> How runtime execution stays explicit and replayable after build-time discovery.

Peel keeps a strict boundary between build time and runtime.

<Info>
  Build time can use reverse engineering, browser or network capture, official-surface discovery, and verification loops. Runtime never replans and never calls back into a model. It only executes the published endpoint contract.
</Info>

## Runtime contract

You call the runtime through one of the public adapters:

* `POST /v1/apis/{api_id}/endpoints/{endpoint_name}:call`
* MCP tool `call_endpoint`

Each published endpoint carries the contract Peel compiled at build time: method, schemas, auth requirement, and a stored transport plan. See [How it works](/getting-started/how-it-works#what-gets-published) for the full field list.

<Steps>
  <Step title="Build">
    Peel investigates the target, verifies candidate surfaces, and compiles an endpoint contract.
  </Step>

  <Step title="Publish">
    The contract is stored as a binding/version-backed API with named endpoints.
  </Step>

  <Step title="Run">
    Every later call uses that stored contract. Runtime can execute only the transport steps already compiled into that endpoint.
  </Step>
</Steps>

## Runtime transport modes

Every compiled endpoint carries exactly one execution transport. The transport is chosen at build time, and runtime never switches into a new investigation mode.

<Columns cols={2}>
  <Card title="Replay" icon="repeat">
    `http_replay` and `graphql_replay` issue deterministic requests against a compiled request surface. They are the cheapest and most stable options when the target exposes a usable request shape.
  </Card>

  <Card title="Flow" icon="git-branch">
    `http_flow` executes a fixed multi-step request chain when one request is not enough to produce the result.
  </Card>

  <Card title="HTML (TLS)" icon="file-text">
    `html_tls` performs a deterministic TLS fetch and parses the response HTML. It is used when the target has no stable request surface but is visible to a plain HTTP client.
  </Card>

  <Card title="Compiled Artifact" icon="box">
    `custom_api_artifact` runs a policy-checked deterministic artifact compiled during build. It receives fetched page evidence through Peel's runtime path and cannot use network, browser, filesystem, package install, environment, eval, or model access.
  </Card>
</Columns>

For a compiled endpoint, runtime may use:

* a single replay request
* a fixed multi-step request flow
* a TLS fetch plus HTML extraction
* a policy-checked compiled artifact over fetched evidence
* a fallback step that was already compiled into the stored contract

Runtime does not invent a new transport, discover a fresh hidden API, or plan browser actions at call time. When a target needs browser evidence, that work belongs in the build pipeline before publication. The replay script or compiled artifact is fixed at build time and does not change between calls.

A minimal endpoint record looks like this. `method` records the compiled target transport method; the Peel-facing runtime route is still always `POST /v1/apis/{api_id}/endpoints/{endpoint_name}:call`.

```json theme={null}
{
  "endpoint_name": "get_top_stories",
  "endpoint_type": "data",
  "auth_requirement": "public",
  "method": "GET"
}
```

## `session_required` stays separate

`session_required` endpoints execute against a target-site session created by a compiled `login` endpoint, not your Peel host credentials. If a protected endpoint is called without both `session_id` and `encryption_key`, runtime rejects the call before it reaches the target.

The full credential flow, header precedence, and scope boundaries are covered in [Authenticated APIs](/features/authenticated-apis).

## What runtime does not do

* **Programmable browser sessions.** Runtime does not click through flows, fill forms dynamically, or react to UI state at call time.
* **Runtime browser fallback.** If a TLS fetch hits an anti-bot or JavaScript-only wall, runtime marks the endpoint for stronger build-time evidence and returns a structured retry/rebuild error instead of launching a browser.
* **Open-ended UI interaction.** Runtime never decides what to click next. All interactions that matter for a result are pinned at build time.
* **Hidden runtime replanning.** A published endpoint's transport plan is frozen. Runtime cannot pick a different request shape or discover a new hidden API mid-call.
* **Generated-code escape hatches.** Compiled artifacts cannot call `fetch`, read files, inspect environment variables, import packages dynamically, or invoke LLM/browser/shell APIs.
* **Legacy scraper-only endpoints.** Everything runtime executes is backed by a binding-versioned API contract.

The goal is stable behavior. A published endpoint runs the same stored contract, with only the compiled transport steps available.

## Related pages

* [How it works](/getting-started/how-it-works)
* [Authentication](/getting-started/authentication)
* [Authenticated APIs](/features/authenticated-apis)
* [Errors](/reference/errors)