openapi: 3.1.0
info:
  title: ANU Quantum Numbers (AQN) API
  version: '1.0'
  summary: Live quantum random numbers generated by the ANU Quantum Optics group.
  description: >-
    The ANU Quantum Numbers (AQN) API is the current, AWS-hosted quantum random number
    service operated by The Australian National University. It supersedes the legacy
    QRNG@ANU PHP endpoint at qrng.anu.edu.au, which ANU states will be "scaled back and
    eventually retired". Randomness is sourced from measurements of the quantum vacuum
    performed by the ANU Quantum Optics group; the service returns arrays of unsigned
    integers or hexadecimal blocks. A free API key is required and is issued self-serve
    at https://quantumnumbers.anu.edu.au.


    OPERATOR: institution. api.quantumnumbers.anu.edu.au is under ANU's own registrable
    domain (anu.edu.au) and the service is run by ANU on its own AWS account. This is not
    a vendor contract running under an institutional name.


    PROVENANCE: this document is DERIVED by API Evangelist from ANU's own published API
    documentation (the parameter table, the curl form and the three worked examples served
    at https://quantumnumbers.anu.edu.au/documentation). ANU publishes no OpenAPI of its
    own. The response envelope is confirmed against a live call to the legacy endpoint,
    which ANU documents as returning the same JSON contract.
  contact:
    name: QRNG@ANU
    email: qrng@anu.edu.au
    url: https://quantumnumbers.anu.edu.au/
  termsOfService: https://www.anu.edu.au/disclaimer
  x-operator: institution
  x-operator-evidence: >-
    api.quantumnumbers.anu.edu.au resolves under anu.edu.au; documentation, signup and
    contact address (qrng@anu.edu.au) are all ANU's.
  x-provenance:
    method: derived
    generated: '2026-08-19'
    source: https://quantumnumbers.anu.edu.au/documentation
    derived_by: API Evangelist university pipeline
servers:
  - url: https://api.quantumnumbers.anu.edu.au
    description: Production (AWS API Gateway, ANU-operated). Returns 403 {"message":"Forbidden"} without a valid x-api-key.
security:
  - ApiKeyAuth: []
tags:
  - name: Random Numbers
    description: Retrieval of quantum-generated random values.
paths:
  /:
    get:
      operationId: getQuantumRandomNumbers
      summary: Request an array of quantum random numbers
      description: >-
        Returns an array of quantum random values of the requested data type and length.
        For the hexadecimal types the size parameter sets the number of bytes in each
        returned block. Requests without a valid x-api-key header are rejected by the
        gateway with 403.
      tags: [ Random Numbers ]
      parameters:
        - name: length
          in: query
          required: true
          description: Number of values to return. Must be between 1 and 1024.
          schema:
            type: integer
            minimum: 1
            maximum: 1024
            examples: [ 10 ]
        - name: type
          in: query
          required: true
          description: >-
            Data type of the returned values. uint8 returns integers 0-255, uint16 returns
            integers 0-65535, hex8 returns hexadecimal characters 00-ff, hex16 returns
            hexadecimal characters 0000-ffff.
          schema:
            type: string
            enum: [ uint8, uint16, hex8, hex16 ]
            examples: [ uint8 ]
        - name: size
          in: query
          required: false
          description: >-
            Block size. Only required for the hex8 and hex16 data types; sets the length of
            each returned block. Must be between 1 and 10.
          schema:
            type: integer
            minimum: 1
            maximum: 10
            examples: [ 2 ]
      responses:
        '200':
          description: An array of quantum random values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuantumNumbersResponse'
              examples:
                uint8:
                  summary: Ten integers between 0 and 255
                  value:
                    type: uint8
                    length: 10
                    data: [ 74, 205, 98, 159, 3, 241, 88, 17, 130, 62 ]
                    success: true
                hex16:
                  summary: Ten two-byte hexadecimal blocks
                  value:
                    type: hex16
                    length: 10
                    size: 2
                    data: [ '4acd', '629f', '03f1', '5811', '823e', 'b0c4', '17aa', '9d50', 'e213', '6f88' ]
                    success: true
        '403':
          description: Missing or invalid API key. Returned by the AWS API Gateway before the service is reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              examples:
                forbidden:
                  value:
                    message: Forbidden
        '429':
          description: Request quota for the API key exceeded.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Free API key issued self-serve after registration at
        https://quantumnumbers.anu.edu.au. Sent on every request as the x-api-key header.
  schemas:
    QuantumNumbersResponse:
      type: object
      required: [ type, length, data, success ]
      properties:
        type:
          type: string
          enum: [ uint8, uint16, hex8, hex16 ]
          description: Echo of the requested data type.
        length:
          type: integer
          minimum: 1
          maximum: 1024
          description: Echo of the requested array length.
        size:
          type: integer
          minimum: 1
          maximum: 10
          description: Echo of the requested block size. Present for the hexadecimal types.
        data:
          type: array
          description: >-
            The quantum random values. Integers for uint8 and uint16; lowercase hexadecimal
            strings for hex8 and hex16.
          items:
            oneOf:
              - type: integer
              - type: string
        success:
          type: boolean
          description: True when the request was served.
    GatewayError:
      type: object
      properties:
        message:
          type: string
          description: Gateway-level error message, e.g. "Forbidden".