corsproxy-dev Proxy API

openapi: 3.2.0
info:
  title: corsproxy.dev Proxy API
  version: 0.1.0
  description: 'Managed CORS proxy API. Programmatic surface for the hosted runtime at

    `https://api.corsproxy.dev`. The same wire protocol is implemented by

    the MIT-licensed Go runtime at

    if you want to self-host.


    Auth: an API key, as `?key=sk_live_…` (browsers) or the `X-API-Key`

    header (servers). Keys are locked to their allowed origins, so server

    callers also send an allowed `Origin` header. API keys only work on the

    endpoints below; account management happens in the dashboard.


    Rate limits:

    - Free plan: 500 requests/day per account, enforced atomically by a

    per-user Durable Object. Over the limit returns `429`.'
  contact:
    name: corsproxy.dev support
    email: contact@corsproxy.dev
    url: https://corsproxy.dev/
  license:
    name: MIT (runtime)
    url: https://github.com/melihbirim/corsproxy/blob/main/LICENSE
servers:
- url: https://api.corsproxy.dev
  description: Production
tags:
- name: Proxy
paths:
  /proxy:
    get:
      $ref: '#/paths/~1v1~1proxy/get'
      tags:
      - Proxy
      summary: Get proxy
      x-summary-source: derived
      operationId: getProxy
      x-operation-id-source: derived
    post:
      $ref: '#/paths/~1v1~1proxy/post'
      tags:
      - Proxy
      summary: Create proxy
      x-summary-source: derived
      operationId: postProxy
      x-operation-id-source: derived
  /v1/proxy:
    get:
      tags:
      - Proxy
      summary: Forward a GET request to an upstream URL
      description: 'The core proxy. Sends `GET ` upstream and rewrites the response

        with permissive CORS headers so a browser can read it.

        Rejections return JSON `{ success: false, code, error }` with a stable

        reason key in `code` (e.g. RATE_LIMIT_EXCEEDED, API_KEY_ORIGIN_NOT_ALLOWED,

        BLOCKED_HOST, UPSTREAM_UNREACHABLE). Full list:

        https://corsproxy.dev/docs/#errors'
      parameters:
      - in: query
        name: url
        required: true
        description: Absolute URL of the upstream API to call.
        schema:
          type: string
          format: uri
          example: https://api.github.com/users/octocat
      - in: query
        name: key
        required: false
        description: API key for browser callers. Server callers should use the `X-API-Key` header instead.
        schema:
          type: string
          example: REDACTED_STRIPE_KEY
      - in: header
        name: X-API-Key
        required: false
        description: API key for server-side callers.
        schema:
          type: string
      - in: query
        name: ttl
        required: false
        description: Pro/Enterprise. Cache 200 responses at the edge for this many seconds (1-86400). Response has X-Cache HIT or MISS. 403 on Free.
        schema:
          type: integer
          minimum: 1
          maximum: 86400
      - in: query
        name: reqHeaders
        required: false
        description: Repeatable `name:value` header to set on the upstream request; empty value removes it. Max 20.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - in: query
        name: resHeaders
        required: false
        description: Repeatable `name:value` header to set on the response; empty value removes it. Access-Control-* cannot be changed. Max 20.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      responses:
        '200':
          description: Upstream returned a successful response. Body and most headers passed through.
        '400':
          description: 'Bad request. Reason keys: MISSING_TARGET_URL, INVALID_TARGET_URL, INVALID_TTL, INVALID_HEADER_OVERRIDE.'
        '401':
          description: 'API key problem. Reason keys: MISSING_API_KEY, INVALID_API_KEY, API_KEY_REVOKED.'
        '403':
          description: 'Not allowed. Reason keys: API_KEY_ORIGIN_NOT_ALLOWED, TARGET_NOT_ALLOWED, BLOCKED_HOST, PROXY_LOOP_DETECTED, UNSAFE_TARGET, BLOCKED_CONTENT, PRO_FEATURE_REQUIRED, TERMS_NOT_ACCEPTED, ACCOUNT_SUSPENDED, ACCOUNT_DELETED.'
        '413':
          description: 'Request body over 10 MB. Reason key: REQUEST_TOO_LARGE.'
        '429':
          description: 'Daily request or bandwidth limit reached. Reason keys: RATE_LIMIT_EXCEEDED, BANDWIDTH_LIMIT_EXCEEDED. Resets at midnight UTC.'
        '502':
          description: 'Upstream problem. Reason keys: RESPONSE_TOO_LARGE, UPSTREAM_UNREACHABLE. (If the upstream itself returns an error, its status and body are passed through with no reason key.)'
      operationId: getV1Proxy
      x-operation-id-source: derived
    post:
      tags:
      - Proxy
      summary: Forward a POST request to an upstream URL
      parameters:
      - $ref: '#/paths/~1v1~1proxy/get/parameters/0'
      - $ref: '#/paths/~1v1~1proxy/get/parameters/1'
      - $ref: '#/paths/~1v1~1proxy/get/parameters/2'
      requestBody:
        required: false
        description: Pass-through to the upstream URL.
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Upstream response
          with CORS headers added.: null
        '400':
          description: 'Bad request. Reason keys: MISSING_TARGET_URL, INVALID_TARGET_URL, INVALID_TTL, INVALID_HEADER_OVERRIDE.'
        '401':
          description: 'API key problem. Reason keys: MISSING_API_KEY, INVALID_API_KEY, API_KEY_REVOKED.'
        '403':
          description: 'Not allowed. Reason keys: API_KEY_ORIGIN_NOT_ALLOWED, TARGET_NOT_ALLOWED, BLOCKED_HOST, PROXY_LOOP_DETECTED, UNSAFE_TARGET, BLOCKED_CONTENT, PRO_FEATURE_REQUIRED, TERMS_NOT_ACCEPTED, ACCOUNT_SUSPENDED, ACCOUNT_DELETED.'
        '413':
          description: 'Request body over 10 MB. Reason key: REQUEST_TOO_LARGE.'
        '429':
          description: 'Daily request or bandwidth limit reached. Reason keys: RATE_LIMIT_EXCEEDED, BANDWIDTH_LIMIT_EXCEEDED. Resets at midnight UTC.'
        '502':
          description: 'Upstream problem. Reason keys: RESPONSE_TOO_LARGE, UPSTREAM_UNREACHABLE. (If the upstream itself returns an error, its status and body are passed through with no reason key.)'
      operationId: postV1Proxy
      x-operation-id-source: derived
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key