openapi: 3.0.3
info:
  title: Bypass Censorship API
  description: |
    The Bypass Censorship API allows publishers to interact with the Bypass Censorship platform and to obtain short links,
    snapshot links, and mirror links for their content.
    
    **Note**: This documentation is generic and applies to any deployment of the Bypass Censorship platform.
    For the base URL and authentication details specific to your use, contact your vendor.
  version: 1.0.0
servers:
  - url: https://example.com
    description: Example server
paths:
  /me:
    get:
      summary: Retrieve information about the authenticated user's pool
      parameters:
        - name: key
          in: query
          description: The API key of the pool. If not provided, the public API key is used.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: Information about the user's pool
        '403':
          description: Invalid API key
  /link:
    get:
      summary: Generate a circumvention link for a specific resource
      parameters:
        - name: url
          in: query
          description: The URL for which a circumvention link needs to be generated.
          required: true
          schema:
            type: string
        - name: type
          in: query
          description: |
            The type of link to generate. Valid values are "live", "short", or "snapshot".
            If not provided, "direct" is used.
          required: false
          schema:
            type: string
            enum: [live, short, snapshot, direct]
        - name: key
          in: query
          description: The API key of the pool. If not provided, the public API key is used.
          required: false
          schema:
            type: string
        - name: expiry
          in: query
          description: |
            The duration that a snapshot will remain published for. Valid values are "long" and "short".
            If not provided, "short" is used.
          required: false
          schema:
            type: string
            enum: [long, short]
        - name: footer_text
          in: query
          description: Defines the footer text to be used when publishing a snapshot.
          required: false
          schema:
            type: string
        - name: footer_link
          in: query
          description: Defines the footer link to be used when publishing a snapshot.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: Generated circumvention link
        '403':
          description: Resource not on a supported domain
        '404':
          description: No live mirror exists for the resource
        '500':
          description: Could not generate a snapshot for the resource
  /{hash}:
    get:
      summary: Redirect to the live mirror associated with the given hash
      parameters:
        - name: hash
          in: path
          description: The hash associated with the short link
          required: true
          schema:
            type: string
        - name: force
          in: query
          description: Always redirect to a mirror and ignore GeoIP information.
          required: false
          schema:
            type: boolean
        - name: force_ip
          in: query
          description: Override the client IP address and base the GeoIP lookup on this IP address instead.
          required: false
          schema:
            type: string
      responses:
        '302':
          description: Redirects the client to the original URL
          headers:
            Location:
              description: The URL of the live mirror
              schema:
                type: string
        '404':
          description: The hash is invalid or not found
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: query
      name: key