openapi: 3.0.3
info:
  title: Random User Generator API
  description: |
    Free, open-source REST API that generates random user data for application testing,
    prototyping, and demo content. Returns rich, realistic synthetic user records
    (name, location, login, contact, picture, identification) across multiple
    nationalities, with deterministic reproducibility via seeds.

    Powered by the open-source project https://github.com/RandomAPI/Randomuser.me-Node
    and funded by community donations (no API key, no rate limit gate).
  version: "1.4"
  contact:
    name: RandomAPI
    url: https://randomuser.me
  license:
    name: MIT
    url: https://github.com/RandomAPI/Randomuser.me-Node/blob/master/LICENSE
  x-generated-from: documentation
  x-source-url: https://randomuser.me/documentation
  x-last-validated: "2026-05-29"

servers:
  - url: https://randomuser.me/api
    description: Production API (auto-selects latest version)
  - url: https://randomuser.me/api/1.4
    description: Pinned to version 1.4

tags:
  - name: Users
    description: Generate one or more synthetic user records.

paths:
  /:
    get:
      operationId: generateUsers
      summary: Generate Random Users
      description: |
        Generate one or more random user records. Supports controlling result count,
        gender, nationality mix, included/excluded fields, password composition,
        format (JSON/CSV/YAML/XML/PrettyJSON), seeded reproducibility, and pagination.
      tags:
        - Users
      parameters:
        - name: results
          in: query
          description: Number of user records to generate. Maximum 5000 per request.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 5000
            default: 1
          example: 10
        - name: gender
          in: query
          description: Restrict to a single gender. Omit or use any other value to return both.
          required: false
          schema:
            type: string
            enum: [male, female]
          example: female
        - name: nat
          in: query
          description: |
            Comma-separated list of two-letter nationality codes. Supported (v1.4):
            AU, BR, CA, CH, DE, DK, ES, FI, FR, GB, IE, IN, IR, MX, NL, NO, NZ,
            RS, TR, UA, US. Omit for a mix of all nationalities.
          required: false
          schema:
            type: string
          example: us,gb,fr
        - name: inc
          in: query
          description: |
            Comma-separated list of top-level fields to include. Allowed values:
            gender, name, location, email, login, registered, dob, phone, cell,
            id, picture, nat. Mutually exclusive with `exc`.
          required: false
          schema:
            type: string
          example: name,email,nat
        - name: exc
          in: query
          description: |
            Comma-separated list of top-level fields to exclude. Allowed values
            same as `inc`. Mutually exclusive with `inc`.
          required: false
          schema:
            type: string
          example: login
        - name: seed
          in: query
          description: |
            Deterministic seed. The same seed (with the same page, results, and
            version) always returns the same users.
          required: false
          schema:
            type: string
          example: foobar
        - name: page
          in: query
          description: |
            Page number (1-based) for paginated seeded results. Use with `seed`
            and a fixed `results` value to walk a stable dataset.
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 3
        - name: format
          in: query
          description: |
            Response serialization format. Defaults to JSON.
          required: false
          schema:
            type: string
            enum: [json, pretty, csv, yaml, xml]
            default: json
          example: csv
        - name: password
          in: query
          description: |
            Password composition rules: `CHARSETS,MIN-MAX` or `CHARSETS,MAX`.
            Charsets: special, upper, lower, number (comma-separated, in any order).
            Default: ~10k top-used passwords; otherwise 8-64 characters.
          required: false
          schema:
            type: string
          example: upper,lower,number,8-16
        - name: dl
          in: query
          description: |
            If present, returns the response as a file download with the
            appropriate extension for the requested `format`.
          required: false
          schema:
            type: boolean
        - name: noinfo
          in: query
          description: |
            If present, omits the `info` envelope (seed, results, page, version)
            from the response.
          required: false
          schema:
            type: boolean
        - name: callback
          in: query
          description: |
            JSONP callback function name. Only honored for JSON formats.
          required: false
          schema:
            type: string
          example: randomuserdata
      responses:
        "200":
          description: A randomly generated user payload.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
              examples:
                singleUser:
                  summary: Default request (one user)
                  value:
                    results:
                      - gender: female
                        name: { title: Miss, first: Jennie, last: Nichols }
                        email: jennie.nichols@example.com
                        nat: US
                    info:
                      seed: 56d27f4a53bd5441
                      results: 1
                      page: 1
                      version: "1.4"
            text/csv:
              schema:
                type: string
            application/xml:
              schema:
                type: string
            application/x-yaml:
              schema:
                type: string
        "500":
          description: Server error from the generator.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /{version}/:
    get:
      operationId: generateUsersVersioned
      summary: Generate Random Users (Pinned Version)
      description: |
        Same as `generateUsers` but pinned to a specific API version so future
        releases cannot break the response shape. Supported versions: 1.0, 1.1,
        1.2, 1.3, 1.4.
      tags:
        - Users
      parameters:
        - name: version
          in: path
          required: true
          description: API version to pin (e.g. `1.4`).
          schema:
            type: string
            enum: ["1.0", "1.1", "1.2", "1.3", "1.4"]
          example: "1.4"
        - $ref: "#/paths/~1/get/parameters/0"
        - $ref: "#/paths/~1/get/parameters/1"
        - $ref: "#/paths/~1/get/parameters/2"
        - $ref: "#/paths/~1/get/parameters/3"
        - $ref: "#/paths/~1/get/parameters/4"
        - $ref: "#/paths/~1/get/parameters/5"
        - $ref: "#/paths/~1/get/parameters/6"
        - $ref: "#/paths/~1/get/parameters/7"
        - $ref: "#/paths/~1/get/parameters/8"
        - $ref: "#/paths/~1/get/parameters/9"
        - $ref: "#/paths/~1/get/parameters/10"
        - $ref: "#/paths/~1/get/parameters/11"
      responses:
        "200":
          description: A randomly generated user payload.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

components:
  schemas:
    UserResponse:
      type: object
      description: Standard envelope returned by the generator.
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/User"
        info:
          $ref: "#/components/schemas/Info"
      required: [results, info]

    Info:
      type: object
      description: Metadata about the generated batch.
      properties:
        seed:
          type: string
          example: 56d27f4a53bd5441
        results:
          type: integer
          example: 1
        page:
          type: integer
          example: 1
        version:
          type: string
          example: "1.4"
      required: [seed, results, page, version]

    User:
      type: object
      description: A single synthetic user record.
      properties:
        gender:
          type: string
          enum: [male, female]
          example: female
        name:
          $ref: "#/components/schemas/Name"
        location:
          $ref: "#/components/schemas/Location"
        email:
          type: string
          format: email
          example: jennie.nichols@example.com
        login:
          $ref: "#/components/schemas/Login"
        dob:
          $ref: "#/components/schemas/DateWithAge"
        registered:
          $ref: "#/components/schemas/DateWithAge"
        phone:
          type: string
          example: "(272) 790-0888"
        cell:
          type: string
          example: "(489) 330-2385"
        id:
          $ref: "#/components/schemas/Id"
        picture:
          $ref: "#/components/schemas/Picture"
        nat:
          type: string
          description: ISO 3166-1 alpha-2 country code for the user's nationality.
          example: US

    Name:
      type: object
      properties:
        title:
          type: string
          example: Miss
        first:
          type: string
          example: Jennie
        last:
          type: string
          example: Nichols

    Location:
      type: object
      properties:
        street:
          type: object
          properties:
            number:
              type: integer
              example: 8929
            name:
              type: string
              example: Valwood Pkwy
        city:
          type: string
          example: Billings
        state:
          type: string
          example: Michigan
        country:
          type: string
          example: United States
        postcode:
          oneOf:
            - type: string
            - type: integer
          example: "63104"
        coordinates:
          type: object
          properties:
            latitude:
              type: string
              example: "-69.8246"
            longitude:
              type: string
              example: "134.8719"
        timezone:
          type: object
          properties:
            offset:
              type: string
              example: "+9:30"
            description:
              type: string
              example: Adelaide, Darwin

    Login:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          example: 7a0eed16-9430-4d68-901f-c0d4c1c3bf00
        username:
          type: string
          example: yellowpeacock117
        password:
          type: string
          example: addison
        salt:
          type: string
          example: sld1yGtd
        md5:
          type: string
          example: ab54ac4c0be9480ae8fa5e9e2a5196a3
        sha1:
          type: string
          example: edcf2ce613cbdea349133c52dc2f3b83168dc51b
        sha256:
          type: string
          example: 48df5229235ada28389b91e60a935e4f9b73eb4bdb855ef9258a1751f10bdc5d

    DateWithAge:
      type: object
      properties:
        date:
          type: string
          format: date-time
          example: 1992-03-08T15:13:16.688Z
        age:
          type: integer
          example: 30

    Id:
      type: object
      properties:
        name:
          type: string
          example: SSN
          description: Identifier scheme (varies by nationality; may be empty).
        value:
          type: string
          nullable: true
          example: 405-88-3636

    Picture:
      type: object
      properties:
        large:
          type: string
          format: uri
          example: https://randomuser.me/api/portraits/men/75.jpg
        medium:
          type: string
          format: uri
          example: https://randomuser.me/api/portraits/med/men/75.jpg
        thumbnail:
          type: string
          format: uri
          example: https://randomuser.me/api/portraits/thumb/men/75.jpg

    Error:
      type: object
      properties:
        error:
          type: string
          example: "Uh oh, something has gone wrong. Please tweet us @randomapi about the issue. Thank you."
      required: [error]