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

# Exporting an API

> Download a completed Peel API as an OpenAPI 3.1 spec or an MCP tool manifest.

Every completed Peel API can be exported in two machine-readable formats. Both exports describe the same compiled endpoint contract that REST, MCP, and CLI runtime calls use. Use the format that fits your target system.

| Export                | Route                                   | Use it to                                                                                                                         |
| --------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **OpenAPI 3.1 spec**  | `GET /v1/apis/{api_id}/exports/openapi` | Bootstrap a typed SDK, import into Postman, Insomnia, or Stoplight, or register the API with a third-party gateway.               |
| **MCP tool manifest** | `GET /v1/apis/{api_id}/exports/mcp`     | Register the API's endpoints as tools in an MCP-compatible agent runtime that cannot talk to the hosted Peel MCP server directly. |

For server-side REST usage, send `X-API-Key`. Signed-in browser sessions are also accepted by the same routes. Exports succeed only after Peel has published exportable endpoints; failed or still-building APIs return `API_NOT_EXPORTABLE` with a pointer back to API detail or health diagnostics.

CLI equivalent:

```bash theme={null}
peel apis export <api-id> --format openapi > peel-api.openapi.json
peel apis export <api-id> --format mcp > peel-api.mcp.json
```

## Download the OpenAPI spec

<CodeGroup>
  ```bash cURL theme={null}
  curl "$PEEL_API_BASE/v1/apis/$API_ID/exports/openapi" \
    -H "X-API-Key: $PEEL_API_KEY" \
    -o peel-api.openapi.json
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    `${process.env.PEEL_API_BASE}/v1/apis/${apiId}/exports/openapi`,
    { headers: { "X-API-Key": process.env.PEEL_API_KEY } },
  );
  const spec = await res.json();
  ```

  ```python Python theme={null}
  res = requests.get(
      f"{os.environ['PEEL_API_BASE']}/v1/apis/{api_id}/exports/openapi",
      headers={"X-API-Key": os.environ["PEEL_API_KEY"]},
  )
  spec = res.json()
  ```
</CodeGroup>

The returned document is an OpenAPI 3.1 spec describing every published endpoint on the API:

* **`servers`**: points at the API-specific execution base, for example `/v1/apis/{api_id}/endpoints` in hosted exports. Generated clients resolve endpoint paths relative to that base.
* **`paths`**: one relative call path per endpoint, for example `/list_products:call`, with the compiled `input_schema` as the request body and the `ExecutionEnvelope` as the response shape. Hosted call operations use `POST` even when the compiled transport talks to the source site with `GET`; inspect `x-target-method` when you need the compiled transport method. Operation extensions also expose `x-endpoint-name`, `x-endpoint-type`, `x-auth-requirement`, runtime policy, and compact build-time verification metadata so SDK generators and agent registries do not need to infer the endpoint contract from the path.
* **`components.schemas`**: the `input_schema`, `output_schema`, and normalized runtime envelope shapes Peel compiled for each endpoint. Public hosted exports describe the same sanitized call envelope returned by `:call`: `status`, `status_code`, `data`, `error`, `error_code`, `execution_time`, plus optional transport, session, and clipped `raw_output` fields. API identity and auth capability fields live on the API detail and export metadata, not inside each endpoint call response body.
* **`security`**: declares `X-API-Key` as the required auth scheme.

You can feed the exported spec into any standard OpenAPI toolchain:

```bash theme={null}
# Generate a typed TypeScript client
npx openapi-typescript peel-api.openapi.json -o peel-api.ts

# Generate a Python client
openapi-generator-cli generate -i peel-api.openapi.json -g python -o ./peel_client
```

## Download the MCP manifest

<CodeGroup>
  ```bash cURL theme={null}
  curl "$PEEL_API_BASE/v1/apis/$API_ID/exports/mcp" \
    -H "X-API-Key: $PEEL_API_KEY" \
    -o peel-api.mcp.json
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    `${process.env.PEEL_API_BASE}/v1/apis/${apiId}/exports/mcp`,
    { headers: { "X-API-Key": process.env.PEEL_API_KEY } },
  );
  const manifest = await res.json();
  ```

  ```python Python theme={null}
  res = requests.get(
      f"{os.environ['PEEL_API_BASE']}/v1/apis/{api_id}/exports/mcp",
      headers={"X-API-Key": os.environ["PEEL_API_KEY"]},
  )
  manifest = res.json()
  ```
</CodeGroup>

The MCP manifest lists every published endpoint as a discrete tool with its name, description, JSON Schema input, annotations, and metadata. Tool annotations include planning hints such as `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` when they apply, plus compact public identity fields such as `api_id`, `binding_id`, `version_id`, and `endpoint_name`. Endpoint metadata includes `rest_path` plus `rest_method: "POST"` for the Peel-facing call route, `target_method` for the compiled transport method Peel uses against the source site, and the same compact runtime policy and verification metadata as OpenAPI exports. Use the manifest when you want to register Peel's endpoints as tools in an agent runtime that you host yourself, for example, a custom LangChain agent that cannot connect to `https://api.peel.sh/mcp` directly.

For most MCP use cases, connect to the hosted MCP server instead. See [MCP server](/features/mcp-server). Export is mainly for offline, self-hosted, or air-gapped agent setups, or for runtimes that can consume a manifest but cannot talk to `https://api.peel.sh/mcp` directly.

## When to re-export

The exports reflect the API's current published version. After a successful `revise` or `rebuild`, the `version_id` changes and the exported spec will likely differ. Re-export whenever:

* you merge a `revise` that changed endpoint names, input schemas, or output shapes
* a `rebuild` recompiled the transport (`version_id` before and after can confirm this)
* you want to pin a generated client to a specific Peel version

<Info>
  Exports are read-only snapshots. They do not include credentials or any `session_required` session state. They describe the compiled contract, not the runtime execution environment.
</Info>

## Related pages

* [How it works](/getting-started/how-it-works): the build lifecycle that produces these exports
* [MCP server](/features/mcp-server): the hosted MCP surface, which serves the same endpoints live
* [API updates](/features/api-updates): when a rebuild or revise changes what the export contains