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

# Create an API



## OpenAPI

````yaml /openapi.json post /v1/apis
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/apis:
    post:
      tags:
        - APIs
      summary: Create an API
      operationId: createApi
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 255
          description: >-
            Repeating a request with the same key returns the same build without
            starting or charging a second one. The same key with a different
            request returns 409 `idempotency_key_reused`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                instructions:
                  oneOf:
                    - type: string
                    - type: 'null'
                wait_for_completion:
                  type: boolean
                  default: false
                timeout_ms:
                  type: integer
                  minimum: 1000
                  maximum: 300000
              additionalProperties: false
      responses:
        '200':
          description: API creation result.
          content:
            application/json:
              schema:
                type: object
                required:
                  - api
                  - waited
                  - timed_out
                properties:
                  api:
                    $ref: '#/components/schemas/PublicApiDetail'
                  waited:
                    type: boolean
                  timed_out:
                    type: boolean
                additionalProperties: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    PublicApiDetail:
      allOf:
        - $ref: '#/components/schemas/PublicApiSummary'
        - type: object
          required:
            - description
            - source_url
            - error
            - requires_session
            - user_input_prompt
            - endpoints
          properties:
            description:
              oneOf:
                - type: string
                - type: 'null'
            source_url:
              oneOf:
                - type: string
                - type: 'null'
            error:
              oneOf:
                - type: string
                - type: 'null'
            requires_session:
              type: boolean
            user_input_prompt:
              oneOf:
                - type: object
                  additionalProperties: true
                - type: 'null'
            endpoints:
              type: array
              items:
                $ref: '#/components/schemas/PublicEndpoint'
          additionalProperties: false
    PublicApiSummary:
      type: object
      required:
        - id
        - url
        - instructions
        - name
        - status
        - created_at
        - updated_at
        - completed_at
        - endpoint_count
        - failure
        - links
        - build
        - archived
        - repair
      properties:
        id:
          type: string
        url:
          type: string
        instructions:
          oneOf:
            - type: string
            - type: 'null'
        name:
          oneOf:
            - type: string
            - type: 'null'
        status:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        completed_at:
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
        endpoint_count:
          type: integer
        failure:
          oneOf:
            - $ref: '#/components/schemas/PublicApiFailure'
            - type: 'null'
        version_id:
          type: string
        links:
          type: object
          additionalProperties:
            type: string
        build:
          oneOf:
            - $ref: '#/components/schemas/ApiBuild'
            - type: 'null'
        archived:
          type: boolean
        repair:
          oneOf:
            - $ref: '#/components/schemas/ApiRepair'
            - type: 'null'
      additionalProperties: false
    PublicEndpoint:
      type: object
      required:
        - method
        - endpoint_name
        - input_schema
        - output_schema
        - endpoint_type
        - auth_requirement
        - examples
        - initiates_session
      properties:
        method:
          type: string
        endpoint_name:
          type: string
        description:
          oneOf:
            - type: string
            - type: 'null'
        input_schema:
          type: object
          additionalProperties: true
        output_schema:
          type: object
          additionalProperties: true
        endpoint_type:
          type: string
        auth_requirement:
          type: string
        credit_cost:
          type: integer
          minimum: 0
          description: Runs charged per successful call.
        examples:
          type: array
          items:
            $ref: '#/components/schemas/PublicEndpointExample'
        initiates_session:
          type: boolean
      additionalProperties: false
    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
    PublicApiFailure:
      type: object
      required:
        - category
        - code
        - message
        - recommended_action
        - refund_reviewable
        - retryable
        - support_debug_id
        - technical_reason
      properties:
        category:
          type: string
          description: Coarse public category for the failed build.
          enum:
            - access_policy
            - auth_required
            - build_timeout
            - compile_quality
            - infrastructure
            - planner_failure
            - unknown
        code:
          description: >-
            Compact build failure code, usually matching failure_reason_code on
            the API record.
          oneOf:
            - type: string
            - type: 'null'
        message:
          type: string
          description: User-facing summary of the failed build.
        recommended_action:
          type: string
          description: Recommended next action for the API owner.
          enum:
            - contact_support
            - revise_task
            - retry_later
            - try_different_url
            - wait_or_rebuild
        refund_reviewable:
          type: boolean
          description: Whether this failed build should be considered for refund review.
        retryable:
          type: boolean
          description: Whether retrying or rebuilding is expected to help.
        support_debug_id:
          type: string
          description: Quote this when contacting support.
        technical_reason:
          type: string
          description: The precise error the build stopped on.
      additionalProperties: false
    ApiBuild:
      type: object
      required:
        - id
        - kind
        - status
        - created_at
        - updated_at
        - completed_at
        - user_input_prompt
        - progress
        - failure
        - version_id
        - draft
      properties:
        id:
          type: string
        kind:
          type: string
          enum:
            - build
            - rebuild
            - revision
            - repair
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - failed
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        completed_at:
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
        user_input_prompt:
          oneOf:
            - type: object
              additionalProperties: true
            - type: 'null'
        progress:
          type: array
          items:
            type: object
            additionalProperties: true
        failure:
          oneOf:
            - $ref: '#/components/schemas/PublicApiFailure'
            - type: 'null'
        version_id:
          oneOf:
            - type: string
            - type: 'null'
          description: The version this build published or stored; pass it to rollback.
        draft:
          type: boolean
          description: >-
            True when this build stored its version without making it current;
            publish it with rollback.
      additionalProperties: false
    ApiRepair:
      type: object
      required:
        - enabled
        - last_checked_at
        - last_result
        - next_check_at
        - reason
      properties:
        enabled:
          type: boolean
        last_checked_at:
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
        last_result:
          oneOf:
            - type: string
              enum:
                - healthy
                - failing
                - repairing
                - repaired
                - repair_failed
                - incompatible
            - type: 'null'
        next_check_at:
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
        reason:
          oneOf:
            - type: string
            - type: 'null'
      additionalProperties: false
    PublicEndpointExample:
      type: object
      required:
        - kind
        - label
        - request
        - mcp_tool_call
        - curl
        - cli_command
      properties:
        kind:
          type: string
          const: endpoint_call
        label:
          type: string
        request:
          type: object
          required:
            - method
            - path
            - headers
            - body
          properties:
            method:
              type: string
              const: POST
            path:
              type: string
            headers:
              type: object
              additionalProperties:
                type: string
            body:
              type: object
              additionalProperties: true
          additionalProperties: false
        mcp_tool_call:
          type: object
          required:
            - name
            - arguments
          properties:
            name:
              type: string
              enum:
                - call_endpoint
                - call_marketplace_endpoint
            arguments:
              type: object
              required:
                - endpoint_name
                - params
              properties:
                api_id:
                  type: string
                  description: Set for call_endpoint
                marketplace_id:
                  type: string
                  description: Set for call_marketplace_endpoint
                endpoint_name:
                  type: string
                params:
                  type: object
                  additionalProperties: true
                session_id:
                  type: string
                encryption_key:
                  type: string
              additionalProperties: false
          additionalProperties: false
        curl:
          type: string
        cli_command:
          type: string
      additionalProperties: false
  responses:
    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'
    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'
    TooManyRequests:
      description: >-
        A rate limit, the build queue, or a quota. Code quota_exceeded means
        runs, builds, the daily cap or the monthly build budget are used up;
        details.quota says which, with details.limit (details.limit_usd and
        details.used_usd for build_budget), details.used or details.remaining,
        and details.reset_at. Code builds_paused means Peel paused new builds
        for everyone until details.resumes_at. Retry-After gives seconds.
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 1
          description: Seconds to wait before retrying.
        RateLimit:
          schema:
            type: string
          description: >-
            The remaining quota and seconds to reset, such as
            `"dispatch-read";r=0;t=42`.
        RateLimit-Policy:
          schema:
            type: string
          description: >-
            The quota and window in seconds, such as
            `"dispatch-read";q=120;w=60`.
      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

````

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