Noun Project Autocomplete API

openapi: 3.0.3
info:
  title: Noun Project API V2 Autocomplete API
  description: 'The Noun Project API V2 is an OAuth 1.0a-secured REST API that provides

    access to nearly 10 million royalty-free PNG and SVG icons. The API

    supports icon search with style and line-weight filtering, similar-icon

    lookup, collection browsing, custom hex-color recoloring, multiple

    thumbnail sizes, autocomplete suggestions, per-client blocklists, and

    real-time usage telemetry.


    Built on AWS with documented 99.99% uptime, the API serves more than

    300 million requests per month. All requests must be signed with OAuth

    1.0a using the client key and secret obtained from the Noun Project

    developer portal.

    '
  version: '2.0'
  termsOfService: https://thenounproject.com/legal/api-terms-of-use/
  contact:
    name: Noun Project API Support
    url: https://thenounproject.zendesk.com/
  license:
    name: Royalty-Free Commercial Use
    url: https://thenounproject.com/legal/api-terms-of-use/
  x-generated-from: documentation
  x-last-validated: '2026-05-28'
servers:
- url: https://api.thenounproject.com
  description: Noun Project API production endpoint
security:
- oauth1: []
tags:
- name: Autocomplete
  description: Suggest search terms based on a query prefix.
paths:
  /v2/icon/autocomplete:
    get:
      operationId: autocompleteIcons
      summary: Autocomplete Icon Search
      description: Suggest icon search terms based on a query prefix. Returns up to 10 suggested terms ranked by relevance.
      tags:
      - Autocomplete
      parameters:
      - name: query
        in: query
        description: Query prefix used to generate term suggestions.
        required: true
        schema:
          type: string
        example: ro
      - name: blacklist
        in: query
        description: When true, applies the client's configured blocklist.
        required: false
        schema:
          type: boolean
          default: false
      - name: limit
        in: query
        description: Maximum suggestions returned (hard cap of 10).
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 10
          default: 10
      responses:
        '200':
          description: Suggested search terms.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
      - oauth1: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AutocompleteResponse:
      type: object
      description: Autocomplete suggestions for an icon search query.
      properties:
        autocomplete:
          type: array
          description: Suggested search terms ranked by relevance.
          items:
            type: string
          example:
          - rocket
          - rocket ship
          - rocket launch
          - rocket science
        generated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the response was generated.
          example: '2026-05-28T14:00:00Z'
      required:
      - autocomplete
    ErrorResponse:
      type: object
      description: Standard error response payload returned for 4xx and 5xx responses.
      properties:
        error:
          type: string
          description: Machine-readable error code.
          example: rate_limit_exceeded
        message:
          type: string
          description: Human-readable error message.
          example: The monthly quota for this client key has been exceeded.
        status:
          type: integer
          description: HTTP status code echo.
          example: 429
        request_id:
          type: string
          description: Server-generated identifier for the failing request.
          example: req-abc123def456
  responses:
    RateLimited:
      description: The hourly, daily, or monthly request quota has been exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid OAuth 1.0a credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    oauth1:
      type: apiKey
      in: header
      name: Authorization
      description: OAuth 1.0a signed Authorization header constructed with the client key and secret obtained from the Noun Project developer portal. A nonce of at least 8 characters is required. Use any standards-compliant OAuth 1.0a library (requests_oauthlib, Faraday-OAuth, DotNetOpenAuth, etc.).
      x-auth-type: OAuth 1.0a
      x-token-url: https://thenounproject.com/developers/apps/
externalDocs:
  description: Noun Project API Documentation
  url: https://api.thenounproject.com/documentation.html