api-ninjas-com Miscellaneous API

openapi: 3.2.0
info:
  title: Ninjas Miscellaneous API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Miscellaneous
paths:
  /v1/historicalevents:
    get:
      summary: Search for historical events
      description: Searches famous events in history by keyword `text` and/or `year`, `month` and `day`; negative years mean BC. Pagination with `offset` requires premium.
      operationId: getHistoricalEvents
      tags:
      - Miscellaneous
      parameters:
      - name: text
        in: query
        description: Query text to search events by. Use keywords or short phrases for best match results.
        required: false
        schema:
          type: string
      - name: year
        in: query
        description: 4-digit year (e.g. 1776). For BC/BCE years, use a negative integer (e.g. -351 for 351 BC).
        required: false
        schema:
          type: integer
      - name: month
        in: query
        description: Integer month (e.g. 3 for March).
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 12
      - name: day
        in: query
        description: Calendar day of the month.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 31
      - name: offset
        in: query
        description: Number of results to offset pagination. Premium only.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: A list of historical events.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistoricalEventsOpenapi_HistoricalEvent'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalEventsOpenapi_ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalEventsOpenapi_ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalEventsOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
  /v1/historicalfigures:
    get:
      tags:
      - Miscellaneous
      summary: Search for historical figures
      description: Searches notable people from history, ancient to modern, by name with partial matches supported, and returns their records. Requires `name`.
      operationId: searchHistoricalFigures
      parameters:
      - name: name
        in: query
        description: Name of the person to search. Includes partial results (e.g. 'julius' will match Julius Caesar).
        required: true
        schema:
          type: string
      - name: offset
        in: query
        description: Number of results to offset pagination.
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistoricalFigure'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
  /v1/randomimage:
    get:
      summary: Get a random image
      description: Returns a random royalty-free image, optionally constrained by `category`, `width` and `height`. Useful for placeholder or sample imagery.
      operationId: getRandomImage
      tags:
      - Miscellaneous
      parameters:
      - $ref: '#/components/parameters/category'
      - $ref: '#/components/parameters/width'
      - $ref: '#/components/parameters/height'
      responses:
        '200':
          $ref: '#/components/responses/RandomImage'
        '400':
          $ref: '#/components/responses/RandomImageOpenapi_BadRequest'
        '401':
          $ref: '#/components/responses/RandomImageOpenapi_Unauthorized'
        '500':
          $ref: '#/components/responses/RandomImageOpenapi_InternalServerError'
      security:
      - ApiKeyAuth: []
  /v2/randomuser:
    get:
      summary: Get fake random user profiles
      description: Generates fake user profiles such as name, email, address and username for testing or placeholders, with count, gender, age, locale, field selection and seed options.
      operationId: getRandomUsers
      tags:
      - Miscellaneous
      parameters:
      - name: count
        in: query
        description: Number of users to generate (1-10000)
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 10000
          default: 10
      - name: gender
        in: query
        description: Filter by gender
        required: false
        schema:
          type: string
          enum:
          - male
          - female
          - nonbinary
          - any
          default: any
      - name: min_age
        in: query
        description: Minimum age (0-115)
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 115
          default: 0
      - name: max_age
        in: query
        description: Maximum age (0-115)
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 115
          default: 100
      - name: locale
        in: query
        description: Locale for generating localized data (e.g., en_US, de_DE, fr_FR)
        required: false
        schema:
          type: string
          default: en_US
      - name: fields
        in: query
        description: Comma-separated list of fields to include. If not specified, all available fields are returned.
        required: false
        schema:
          type: string
      - name: exclude
        in: query
        description: Comma-separated list of fields to exclude from the response
        required: false
        schema:
          type: string
      - name: seed
        in: query
        description: Seed value for reproducible random data generation
        required: false
        schema:
          type: string
      - name: blank_percentage
        in: query
        description: Percentage of fields to leave blank (0-100)
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 100
          default: 0
      - name: password_length
        in: query
        description: Length of generated passwords (6-128)
        required: false
        schema:
          type: integer
          minimum: 6
          maximum: 128
          default: 12
      - name: nationality
        in: query
        description: Nationality filter
        required: false
        schema:
          type: string
          default: any
      responses:
        '200':
          description: 'Successful response: a list of random user profiles.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RandomUserProfile'
        '400':
          description: Bad Request - Invalid parameters
        '401':
          description: Unauthorized - Invalid or missing API key
        '500':
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
  /v1/unitconversion:
    get:
      tags:
      - Miscellaneous
      summary: Converts between different units of measurement
      description: Converts a numeric value from one unit of measurement to another. Requires `amount` and the source `unit`, with spaces written as underscores.
      operationId: convertUnit
      parameters:
      - name: amount
        in: query
        description: The numerical value to convert.
        required: true
        schema:
          type: number
      - name: unit
        in: query
        description: The source unit to convert from. Spaces should be replaced with underscores.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnitConversionResponse'
        '400':
          $ref: '#/components/responses/UnitConversionOpenapi_BadRequest'
        '401':
          $ref: '#/components/responses/UnitConversionOpenapi_Unauthorized'
        '500':
          $ref: '#/components/responses/UnitConversionOpenapi_InternalServerError'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    HistoricalEventsOpenapi_HistoricalEvent:
      type: object
      properties:
        year:
          type: string
          description: The year of the event, can be a negative value for BC/BCE years.
        month:
          type: string
          description: The month of the event.
        day:
          type: string
          description: The day of the month of the event.
        event:
          type: string
          description: Description of the historical event.
    RandomUserProfile:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        username:
          type: string
          example: kristinward
        password:
          type: string
          example: SecurePass123!
        name:
          type: string
          example: Katherine Gill
        first_name:
          type: string
          example: Katherine
        last_name:
          type: string
          example: Gill
        full_name:
          type: string
          example: Katherine Gill
        prefix:
          type: string
          example: Ms.
        suffix:
          type: string
          example: Jr.
        email:
          type: string
          format: email
          example: jestrada@gmail.com
        phone:
          type: string
          example: +1-555-123-4567
        cell:
          type: string
          example: +1-555-123-4567
        address:
          type: string
          example: 122 Powell Trace Suite 016, Lloydport, SC 08075
        street_address:
          type: string
          example: 122 Powell Trace Suite 016
        city:
          type: string
          example: Lloydport
        state:
          type: string
          example: SC
        postal_code:
          type: string
          example: 08075
        country:
          type: string
          example: United States
        latitude:
          type: number
          format: float
          example: 34.0522
        longitude:
          type: number
          format: float
          example: -118.2437
        timezone:
          type: string
          example: America/Los_Angeles
        dob:
          type: string
          format: date
          example: '1958-04-05'
        age:
          type: integer
          example: 65
        gender:
          type: string
          enum:
          - male
          - female
          - nonbinary
          example: female
        job:
          type: string
          example: Software Engineer
        company:
          type: string
          example: Tech Corp
        company_email:
          type: string
          format: email
          example: katherine.gill@techcorp.com
        ssn:
          type: string
          example: 123-45-6789
        credit_card:
          type: string
          example: 4532-1234-5678-9010
        credit_card_provider:
          type: string
          example: Visa
        iban:
          type: string
          example: GB82WEST12345698765432
        ipv4:
          type: string
          format: ipv4
          example: 192.168.1.1
        ipv6:
          type: string
          format: ipv6
          example: 2001:0db8:85a3:0000:0000:8a2e:0370:7334
        mac_address:
          type: string
          example: 00:1B:44:11:3A:B7
        user_agent:
          type: string
          example: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
        url:
          type: string
          format: uri
          example: https://example.com
        domain:
          type: string
          example: example.com
        picture:
          type: string
          format: uri
          example: https://picsum.photos/200/300
        avatar:
          type: string
          format: uri
          example: https://picsum.photos/200/200
        uuid:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        md5:
          type: string
          example: 5d41402abc4b2a76b9719d911017c592
        sha1:
          type: string
          example: aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
        sha256:
          type: string
          example: 2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae
        locale:
          type: string
          example: en_US
    UnitConversionResponse:
      type: object
      properties:
        type:
          type: string
          description: The measurement type (e.g., length, volume, temperature, etc.).
        unit:
          type: string
          description: The source unit that was converted from.
        amount:
          type: number
          description: The original amount to convert.
        conversions:
          type: object
          additionalProperties:
            type: number
          description: An object containing all the converted values for each unit of the same measurement type.
      required:
      - type
      - unit
      - amount
      - conversions
    HistoricalEventsOpenapi_ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message detailing what went wrong.
    HistoricalFigure:
      type: object
      properties:
        name:
          type: string
          description: Name of the historical figure.
        title:
          type: string
          description: Title or role of the historical figure.
        info:
          type: object
          properties:
            born:
              type: string
              description: Birth date and location.
            died:
              type: string
              description: Death date and location.
            years:
              type: string
              description: Active years.
            awards:
              type: string
              description: Awards received.
            office:
              type: array
              items:
                type: string
              description: Offices held.
            parents:
              type: array
              items:
                type: string
              description: Names of parents.
            spouses:
              type: string
              description: Names of spouses.
            children:
              type: array
              items:
                type: string
              description: Names of children.
            partners:
              type: string
              description: Names of partners.
            conflicts:
              type: array
              items:
                type: string
              description: Conflicts participated in.
            occupation:
              type: array
              items:
                type: string
              description: Occupations.
            notable_work:
              type: array
              items:
                type: string
              description: Notable works.
            resting_place:
              type: string
              description: Location of resting place.
            cause_of_death:
              type: string
              description: Cause of death.
  parameters:
    width:
      in: query
      name: width
      schema:
        type: integer
        default: 640
        minimum: 1
        maximum: 5000
      description: Width of the image to generate. Must be between 1 and 5000. Default value is 640. Premium only.
      required: false
    category:
      in: query
      name: category
      schema:
        type: string
        enum:
        - nature
        - city
        - technology
        - food
        - still_life
        - abstract
        - wildlife
      description: 'Image category. If set, must be one of the following: nature, city, technology, food, still_life, abstract, wildlife. Premium only.'
      required: false
    height:
      in: query
      name: height
      schema:
        type: integer
        default: 480
        minimum: 1
        maximum: 5000
      description: Height of the image to generate. Must be between 1 and 5000. Default value is 480. Premium only.
      required: false
  responses:
    UnitConversionOpenapi_InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    RandomImageOpenapi_BadRequest:
      description: Bad request. The request was unacceptable, often due to missing a required parameter.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    RandomImageOpenapi_Unauthorized:
      description: Unauthorized. No valid API key provided.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    UnitConversionOpenapi_BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    RandomImage:
      description: A random, base64-encoded image in JPEG format.
      content:
        image/jpg:
          schema:
            type: string
            format: binary
    UnitConversionOpenapi_Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    RandomImageOpenapi_InternalServerError:
      description: Internal Server Error. Something went wrong on the API's end.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api