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

> ## Agent Instructions
> Peel builds APIs from a URL and a task. Use only the REST routes under https://api.peel.sh and the hosted MCP server at https://api.peel.sh/mcp. Authenticate with the X-API-Key header, or send the same key as Authorization: Bearer. Errors carry code, message, retryable, retry, docs_url and details; branch on code. The peel CLI and the open-source SDK are not published; do not run npm install peel, which is an unrelated package. The keyless routes need no key and no session: the GET /public/marketplace routes, POST /v1/marketplace/{marketplace_id}/endpoints/{endpoint_name}:call and https://api.peel.sh/mcp/keyless. Account routes take a key or a signed-in session and answer 401 without one. These take only a session from peel.sh and refuse a key: GET /v1/accounts, POST /v1/accounts/join, POST /v1/accounts/{account_id}/leave, POST /v1/team/invites, GET /v1/connected-apps, DELETE /v1/connected-apps/{client_id}, PUT /v1/logins, DELETE /v1/logins, GET /v1/logins/code and the /account/billing routes. Every route with its schemas is in https://docs.peel.sh/openapi.json. Use the exact route, field and error-code names shown in these pages, and read the API Reference tab for request and response schemas.

# Call a public data endpoint from its canonical marketplace version

> Works without a key for public data endpoints: at most 25 calls a day per address and 2,000 a day shared by all calls without a key, both reset at midnight UTC, and the answer carries a `notice`. Past either limit the answer is 429 `try_limit_reached` with `Retry-After`; when the limiter cannot answer the call gets 503 `temporarily_unavailable` with `Retry-After`. A signed-in or sign-in endpoint answers 401 `sign_in_required`, and an endpoint that uses files answers 409 `not_executable`. Without a key, `Idempotency-Key` and session headers are ignored, nothing is stored, and every call runs live.



## OpenAPI

````yaml /openapi.json post /v1/marketplace/{marketplace_id}/endpoints/{endpoint_name}:call
openapi: 3.1.0
info:
  title: Peel API
  version: 0.1.0
  description: >-
    Public Peel API for creating APIs from URLs, inspecting them, calling
    generated endpoints, revising builds, and exporting OpenAPI or MCP
    definitions.
servers:
  - url: https://api.peel.sh
security: []
tags:
  - name: APIs
    description: Create, list, inspect, revise, rebuild, and export APIs.
  - name: Account
    description: Credits and account usage surfaces used by REST and MCP clients.
  - name: Device Auth
    description: CLI browser-login device flow helpers.
  - name: Endpoint Execution
    description: Execute generated endpoints through a stable API resource.
  - name: OAuth
    description: OAuth discovery and token flows for hosted MCP clients.
  - name: MCP
    description: Hosted MCP transport and discovery surface.
  - name: Marketplace
    description: Discover, install, publish, and explicitly contribute APIs.
  - name: Execution Jobs
    description: Start, reconnect, answer and cancel owner-scoped host executions.
  - name: Runs
    description: >-
      Every call, batch item and execution you ran, with its outcome and its
      requests to the site.
  - name: Files
    description: Encrypted owner-scoped files for declared runtime uploads and downloads.
  - name: Logins
    description: >-
      Saved site logins Peel signs in with for endpoints that need a signed-in
      session.
  - name: Webhooks
    description: Signed Standard Webhooks events for builds and execution jobs.
  - name: Schedules
    description: Run a data endpoint on a schedule and hear when its answer changes.
paths:
  /v1/marketplace/{marketplace_id}/endpoints/{endpoint_name}:call:
    post:
      tags:
        - Marketplace
        - Endpoint Execution
      summary: Call a public data endpoint from its canonical marketplace version
      description: >-
        Works without a key for public data endpoints: at most 25 calls a day
        per address and 2,000 a day shared by all calls without a key, both
        reset at midnight UTC, and the answer carries a `notice`. Past either
        limit the answer is 429 `try_limit_reached` with `Retry-After`; when the
        limiter cannot answer the call gets 503 `temporarily_unavailable` with
        `Retry-After`. A signed-in or sign-in endpoint answers 401
        `sign_in_required`, and an endpoint that uses files answers 409
        `not_executable`. Without a key, `Idempotency-Key` and session headers
        are ignored, nothing is stored, and every call runs live.
      operationId: callMarketplaceEndpoint
      parameters:
        - $ref: '#/components/parameters/MarketplaceId'
        - in: path
          name: endpoint_name
          required: true
          schema:
            type: string
            minLength: 1
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 255
          description: >-
            Optional. Scoped to the owner, API and endpoint. A retry with the
            same key and params is not charged again: a successful response up
            to 375 KB is stored and replayed with `Idempotent-Replayed: true`; a
            login response, a larger one or a failed call answers 409 with the
            recorded outcome (`already_finalized`), and a call still running
            answers `request_in_progress`. The same key with different params
            returns 409 `idempotency_key_reused`.
        - in: header
          name: Peel-Shape
          required: false
          schema:
            type: string
          description: >-
            Optional. A JSON shape (see the batch body's `shape`) applied to
            this call's result. A bad shape answers 400 `shape_invalid` before
            the run and costs nothing.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: Endpoint parameters. The body is the endpoint's input.
      responses:
        '200':
          description: Canonical marketplace endpoint execution envelope.
          headers:
            X-Peel-Credits-Charged:
              description: >-
                Runs charged for this execution, in the same units as the credit
                ledger. Zero when the run did not return a result and was
                reversed.
              schema:
                type: integer
                minimum: 0
            X-Peel-Credits-Remaining:
              description: >-
                Authoritative remaining run balance (credits ledger units) after
                execution billing.
              schema:
                type: integer
                minimum: 0
            Peel-Verified:
              description: >-
                The exact program that answered and when it last passed
                verification: `artifact=<sha256 of the published artifact>;
                at=<ISO 8601 time>`. The time is the version's publication, or
                its most recent passing repair check if that is later.
              schema:
                type: string
                pattern: ^artifact=[0-9a-f]{64}; at=.+$
            Server-Timing:
              description: >-
                Where the call's time went, in milliseconds: `pre` (before the
                handler), `admit` (resolve and charge), `run` (the program,
                including the target site) and `settle` (record and finalize).
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicEndpointExecutionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Runtime execution envelope for a target block or policy rejection.
          headers:
            X-Peel-Credits-Charged:
              description: >-
                Runs charged for this execution, in the same units as the credit
                ledger. Zero when the run did not return a result and was
                reversed.
              schema:
                type: integer
                minimum: 0
            X-Peel-Credits-Remaining:
              description: >-
                Authoritative remaining run balance (credits ledger units) after
                execution billing.
              schema:
                type: integer
                minimum: 0
            Peel-Verified:
              description: >-
                The exact program that answered and when it last passed
                verification: `artifact=<sha256 of the published artifact>;
                at=<ISO 8601 time>`. The time is the version's publication, or
                its most recent passing repair check if that is later.
              schema:
                type: string
                pattern: ^artifact=[0-9a-f]{64}; at=.+$
            Server-Timing:
              description: >-
                Where the call's time went, in milliseconds: `pre` (before the
                handler), `admit` (resolve and charge), `run` (the program,
                including the target site) and `settle` (record and finalize).
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicEndpointExecutionResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          description: Runtime execution envelope for extraction or validation failure.
          headers:
            X-Peel-Credits-Charged:
              description: >-
                Runs charged for this execution, in the same units as the credit
                ledger. Zero when the run did not return a result and was
                reversed.
              schema:
                type: integer
                minimum: 0
            X-Peel-Credits-Remaining:
              description: >-
                Authoritative remaining run balance (credits ledger units) after
                execution billing.
              schema:
                type: integer
                minimum: 0
            Peel-Verified:
              description: >-
                The exact program that answered and when it last passed
                verification: `artifact=<sha256 of the published artifact>;
                at=<ISO 8601 time>`. The time is the version's publication, or
                its most recent passing repair check if that is later.
              schema:
                type: string
                pattern: ^artifact=[0-9a-f]{64}; at=.+$
            Server-Timing:
              description: >-
                Where the call's time went, in milliseconds: `pre` (before the
                handler), `admit` (resolve and charge), `run` (the program,
                including the target site) and `settle` (record and finalize).
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicEndpointExecutionResponse'
        '429':
          description: >-
            Runtime execution envelope when the target site rate-limits the run,
            or, without a key, a `try_limit_reached` refusal before any run.
          headers:
            X-Peel-Credits-Charged:
              description: >-
                Runs charged for this execution, in the same units as the credit
                ledger. Zero when the run did not return a result and was
                reversed.
              schema:
                type: integer
                minimum: 0
            X-Peel-Credits-Remaining:
              description: >-
                Authoritative remaining run balance (credits ledger units) after
                execution billing.
              schema:
                type: integer
                minimum: 0
            Peel-Verified:
              description: >-
                The exact program that answered and when it last passed
                verification: `artifact=<sha256 of the published artifact>;
                at=<ISO 8601 time>`. The time is the version's publication, or
                its most recent passing repair check if that is later.
              schema:
                type: string
                pattern: ^artifact=[0-9a-f]{64}; at=.+$
            Server-Timing:
              description: >-
                Where the call's time went, in milliseconds: `pre` (before the
                handler), `admit` (resolve and charge), `run` (the program,
                including the target site) and `settle` (record and finalize).
              schema:
                type: string
            Retry-After:
              description: >-
                Seconds to wait. On a refusal without a key, until midnight UTC
                or a short retry.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PublicEndpointExecutionResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Runtime execution envelope for target transport failure.
          headers:
            X-Peel-Credits-Charged:
              description: >-
                Runs charged for this execution, in the same units as the credit
                ledger. Zero when the run did not return a result and was
                reversed.
              schema:
                type: integer
                minimum: 0
            X-Peel-Credits-Remaining:
              description: >-
                Authoritative remaining run balance (credits ledger units) after
                execution billing.
              schema:
                type: integer
                minimum: 0
            Peel-Verified:
              description: >-
                The exact program that answered and when it last passed
                verification: `artifact=<sha256 of the published artifact>;
                at=<ISO 8601 time>`. The time is the version's publication, or
                its most recent passing repair check if that is later.
              schema:
                type: string
                pattern: ^artifact=[0-9a-f]{64}; at=.+$
            Server-Timing:
              description: >-
                Where the call's time went, in milliseconds: `pre` (before the
                handler), `admit` (resolve and charge), `run` (the program,
                including the target site) and `settle` (record and finalize).
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicEndpointExecutionResponse'
        '503':
          description: >-
            Runtime execution envelope for temporary execution capacity, or,
            without a key, a `temporarily_unavailable` refusal before any run
            when the daily limiter does not answer.
          headers:
            X-Peel-Credits-Charged:
              description: >-
                Runs charged for this execution, in the same units as the credit
                ledger. Zero when the run did not return a result and was
                reversed.
              schema:
                type: integer
                minimum: 0
            X-Peel-Credits-Remaining:
              description: >-
                Authoritative remaining run balance (credits ledger units) after
                execution billing.
              schema:
                type: integer
                minimum: 0
            Peel-Verified:
              description: >-
                The exact program that answered and when it last passed
                verification: `artifact=<sha256 of the published artifact>;
                at=<ISO 8601 time>`. The time is the version's publication, or
                its most recent passing repair check if that is later.
              schema:
                type: string
                pattern: ^artifact=[0-9a-f]{64}; at=.+$
            Server-Timing:
              description: >-
                Where the call's time went, in milliseconds: `pre` (before the
                handler), `admit` (resolve and charge), `run` (the program,
                including the target site) and `settle` (record and finalize).
              schema:
                type: string
            Retry-After:
              description: >-
                Seconds to wait. On a refusal without a key, until midnight UTC
                or a short retry.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PublicEndpointExecutionResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Runtime execution envelope for timeout.
          headers:
            X-Peel-Credits-Charged:
              description: >-
                Runs charged for this execution, in the same units as the credit
                ledger. Zero when the run did not return a result and was
                reversed.
              schema:
                type: integer
                minimum: 0
            X-Peel-Credits-Remaining:
              description: >-
                Authoritative remaining run balance (credits ledger units) after
                execution billing.
              schema:
                type: integer
                minimum: 0
            Peel-Verified:
              description: >-
                The exact program that answered and when it last passed
                verification: `artifact=<sha256 of the published artifact>;
                at=<ISO 8601 time>`. The time is the version's publication, or
                its most recent passing repair check if that is later.
              schema:
                type: string
                pattern: ^artifact=[0-9a-f]{64}; at=.+$
            Server-Timing:
              description: >-
                Where the call's time went, in milliseconds: `pre` (before the
                handler), `admit` (resolve and charge), `run` (the program,
                including the target site) and `settle` (record and finalize).
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicEndpointExecutionResponse'
      security:
        - ApiKeyAuth: []
        - SessionCookieAuth: []
        - {}
components:
  parameters:
    MarketplaceId:
      in: path
      name: marketplace_id
      required: true
      schema:
        type: string
  schemas:
    PublicEndpointExecutionResponse:
      type: object
      required:
        - status
        - status_code
        - data
        - error
        - error_code
        - execution_time
      properties:
        action_outcome:
          type: string
          enum:
            - committed
            - not_committed
            - unknown
            - cancelled
          description: >-
            What the call changed on the target. Present on every failed call
            and on every write. unknown means requests may have been sent.
        retry_safe:
          type: boolean
          description: False when action_outcome is committed or unknown.
        retry:
          type: string
          enum:
            - never
            - fix_request
            - same_key
            - new_key
          description: >-
            Present on every failed call. never: do not repeat it, inspect the
            target first. fix_request: nothing ran, change the request first.
            same_key: repeat the same request with the same Idempotency-Key.
            new_key: nothing was committed, repeat it as a new request.
        status:
          oneOf:
            - type: string
            - type: 'null'
        status_code:
          oneOf:
            - type: number
            - type: 'null'
        data: {}
        credits_charged:
          type: number
        credits_remaining:
          oneOf:
            - type: number
            - type: 'null'
        error:
          oneOf:
            - type: string
            - type: 'null'
        error_code:
          oneOf:
            - type: string
            - type: 'null'
        execution_time:
          oneOf:
            - type: number
            - type: 'null'
        transport:
          oneOf:
            - type: string
              enum:
                - html_browser
                - http_replay
            - type: 'null'
        initiates_session:
          type: boolean
        session_id:
          oneOf:
            - type: string
            - type: 'null'
        encryption_key:
          oneOf:
            - type: string
            - type: 'null'
        session_renewed:
          type: boolean
          description: >-
            True when the session sent was gone and Peel signed in again with
            the saved login; session_id and encryption_key then hold the new
            session, and the old pair no longer works.
        shape:
          type: object
          description: >-
            Present when the call carried a shape. applied: data is in the
            shape's form. skipped: data is the endpoint's own result and reason
            says why.
          properties:
            status:
              type: string
              enum:
                - applied
                - skipped
            reason:
              type: string
            left_out:
              type: array
              items:
                type: string
              description: Row fields the shape's fields leave out
      additionalProperties: true
    ErrorResponse:
      type: object
      required:
        - type
        - title
        - status
        - instance
        - code
        - message
        - retryable
        - retry
        - docs_url
        - details
      properties:
        type:
          type: string
          format: uri
          description: >-
            RFC 9457 problem type: https://docs.peel.sh/errors/ followed by the
            code.
        title:
          type: string
          description: >-
            Short summary of the problem type. The same for every error with
            this code.
        status:
          type: integer
          minimum: 400
          maximum: 599
          description: The HTTP status of this response.
        instance:
          type: string
          description: >-
            This occurrence: urn:peel:request: followed by the request id, which
            x-request-id also carries.
        code:
          type: string
          description: Stable snake_case error code.
        message:
          type: string
        retryable:
          type: boolean
          description: Whether the same request can succeed later.
        retry:
          type: string
          enum:
            - same_key
            - fix_request
          description: >-
            A request answered with this envelope did not commit a write.
            same_key: send the same request again, with the same
            Idempotency-Key. fix_request: change the request, key or plan first.
        docs_url:
          type: string
          format: uri
        details:
          type: object
          additionalProperties: true
      additionalProperties: false
  responses:
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid auth.
      headers:
        WWW-Authenticate:
          schema:
            type: string
          description: OAuth bearer challenge with MCP resource metadata when available.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Requested API or endpoint was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: The requested lifecycle transition conflicts with current API state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    SessionCookieAuth:
      type: apiKey
      in: cookie
      name: better-auth.session_token

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.