openapi: 3.0.3
info:
  title: Bypass Censorship Reflector
  description: The public API for the Bypass Censorship Reflector.
  version: 0.0.1

servers:
  - url: 'https'
paths:
  /link:
    get:
      summary: Get a link to a mirror for the given URL.
      description: |
        If an API key is used, the mirror link will use a mirror for the related pool.
      parameters:
        - name: url
          in: query
          description: The URL to generate the link for.
          schema:
            type: string
            example: https://www.sr2.uk/blog/2022/dynamic-bridges/
        - name: type
          in: query
          schema:
            type: string
            enum: ['direct', 'short', 'onion']
            description: |
              The type of link to generate.
              When no API key is used, the default option is to generate a direct link.
              When an API key is used, the default option is to generate a short link.
      responses:
        200:
          description: The URL for the mirror.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    example: "https://fake.cloudfront.net/blog/2022/dynamic-bridges/"
        403:
          description: The given API key was invalid.
        404:
          description: No link could be generated from the given parameters.
        502:
          description: The application is down for maintenance.
  /me:
    get:
      summary: Get information about the authenticated user.
      responses:
        200:
          description: Information about the authenticated user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: string
                    example: "Link Distribution Team A"
        403:
          description: The given API key was invalid.
        502:
          description: The application is down for maintenance.

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: key

security:
  - ApiKeyAuth: []