openapi: 3.1.0
info:
  title: httpstat
  description: |
    A simple service for generating various HTTP status codes.  
    Use this API to test how your scripts handle different HTTP responses.
  version: 1.0.0
servers:
  - url: https://httpstat.us
paths:
  /{statusCode}:
    get:
      summary: Generate a specific HTTP status code
      description: |
        Generates a response with the given HTTP status code.  
        For JSON responses, include the `Accept: application/json` header.
      parameters:
        - name: statusCode
          in: path
          required: true
          description: The HTTP status code to generate.
          schema:
            type: string
            enum:
              - '100'
              - '101'
              - '102'
              - '103'
              - '200'
              - '201'
              - '202'
              - '203'
              - '204'
              - '205'
              - '206'
              - '207'
              - '208'
              - '226'
              - '300'
              - '301'
              - '302'
              - '303'
              - '304'
              - '305'
              - '306'
              - '307'
              - '308'
              - '400'
              - '401'
              - '402'
              - '403'
              - '404'
              - '405'
              - '406'
              - '407'
              - '408'
              - '409'
              - '410'
              - '411'
              - '412'
              - '413'
              - '414'
              - '415'
              - '416'
              - '417'
              - '418'
              - '421'
              - '422'
              - '423'
              - '424'
              - '425'
              - '426'
              - '428'
              - '429'
              - '431'
              - '451'
              - '500'
              - '501'
              - '502'
              - '503'
              - '504'
              - '505'
              - '506'
              - '507'
              - '508'
              - '510'
              - '511'
              - '419'
              - '420'
              - '440'
              - '444'
              - '449'
              - '450'
              - '460'
              - '463'
              - '494'
              - '495'
              - '496'
              - '497'
              - '498'
              - '499'
              - '520'
              - '521'
              - '522'
              - '523'
              - '524'
              - '525'
              - '526'
              - '527'
              - '530'
              - '561'
        - name: sleep
          in: query
          required: false
          description: >-
            Delay the response by the specified duration in milliseconds (max
            230 seconds for hosted instance).
          schema:
            type: integer
            minimum: 0
            maximum: 300000
      responses:
        '200':
          description: OK
          content:
            text/plain: {}
            application/json: {}
        '400':
          description: Bad Request
        default:
          description: Generated HTTP status code
          content:
            text/plain: {}
            application/json: {}
  /random/{range}:
    get:
      summary: Generate a random HTTP status code
      description: |
        Generates a random HTTP status code from the specified range.  
        Duplicate ranges can increase their probability.
      parameters:
        - name: range
          in: path
          required: true
          description: >-
            The range of HTTP status codes to randomize (e.g.,
            `200,201,500-504`).
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            text/plain: {}
            application/json: {}
        default:
          description: Generated random HTTP status code
          content:
            text/plain: {}
            application/json: {}
components:
  parameters:
    X-HttpStatus-Sleep:
      name: X-HttpStatus-Sleep
      in: header
      description: >-
        Delay the response by the specified duration in milliseconds (max 5
        minutes).
      schema:
        type: integer
        minimum: 0
        maximum: 300000
    X-HttpStatus-Response-CustomHeader:
      name: X-HttpStatus-Response-{CustomHeader}
      in: header
      description: Add custom headers to the response.
      schema:
        type: string
  responses:
    DefaultResponse:
      description: Default response
      content:
        text/plain: {}
        application/json: {}