openapi: 3.0.3
info:
  title: Noun Project API V2
  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
externalDocs:
  description: Noun Project API Documentation
  url: https://api.thenounproject.com/documentation.html
tags:
  - name: Icon
    description: Search, filter, retrieve, and download icons from the Noun Project library.
  - name: Collection
    description: Search and retrieve curated icon collections (icon sets).
  - name: Autocomplete
    description: Suggest search terms based on a query prefix.
  - name: Blocklist
    description: Manage per-client blocklists for icon IDs, collection IDs, and terms.
  - name: Usage
    description: Inspect current API key usage against documented quotas.
paths:
  /v2/icon:
    get:
      operationId: searchIcons
      summary: Search Icons
      description: >-
        Search the Noun Project icon library by query term with optional filters
        for style, line weight, public-domain status, and thumbnail size.
        Returns a paginated list of matching icons.
      tags:
        - Icon
      parameters:
        - name: query
          in: query
          description: Search term used to match icon titles, tags, and descriptions.
          required: true
          schema:
            type: string
          example: rocket
        - name: styles
          in: query
          description: >-
            Comma-separated icon styles to filter by. Common values include
            `solid` and `line`.
          required: false
          schema:
            type: string
          example: solid
        - name: line_weight
          in: query
          description: >-
            Line weight in pixels (1-60) at 512-pixel rendering. Only meaningful
            for line-style icons.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 60
          example: 4
        - name: limit_to_public_domain
          in: query
          description: When true, restricts results to icons released to the public domain.
          required: false
          schema:
            type: boolean
            default: false
          example: false
        - name: thumbnail_size
          in: query
          description: Pixel dimension for returned thumbnail URLs.
          required: false
          schema:
            type: integer
            enum: [42, 84, 200]
            default: 84
          example: 200
        - name: blacklist
          in: query
          description: When true, applies the client's configured blocklist to results.
          required: false
          schema:
            type: boolean
            default: false
          example: true
        - name: include_svg
          in: query
          description: When true, includes raw SVG markup in each icon result.
          required: false
          schema:
            type: boolean
            default: false
          example: false
        - name: limit
          in: query
          description: Maximum number of icons returned per page.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
          example: 50
        - name: prev_page
          in: query
          description: Cursor token returned by a prior response for backward pagination.
          required: false
          schema:
            type: string
        - name: next_page
          in: query
          description: Cursor token returned by a prior response for forward pagination.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Paginated icon search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IconSearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - oauth1: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/icon/{icon_id}:
    get:
      operationId: getIcon
      summary: Get Icon
      description: Retrieve a single icon by its numeric identifier with full metadata.
      tags:
        - Icon
      parameters:
        - $ref: '#/components/parameters/IconId'
        - name: thumbnail_size
          in: query
          description: Pixel dimension for the returned thumbnail URL.
          required: false
          schema:
            type: integer
            enum: [42, 84, 200]
            default: 84
          example: 200
        - name: blacklist
          in: query
          description: When true, returns 404 if the icon is on the client's blocklist.
          required: false
          schema:
            type: boolean
            default: false
          example: true
      responses:
        '200':
          description: Icon details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IconResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - oauth1: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/icon/{icon_id}/more-like-this:
    get:
      operationId: getSimilarIcons
      summary: Get Similar Icons
      description: >-
        Find icons stylistically similar to the supplied icon ID, optionally
        narrowed by a query term. Used to assemble visually consistent icon
        sets from a single seed.
      tags:
        - Icon
      parameters:
        - $ref: '#/components/parameters/IconId'
        - name: query
          in: query
          description: Optional search term to narrow similar-icon candidates.
          required: false
          schema:
            type: string
          example: spaceship
        - name: limit_to_public_domain
          in: query
          description: When true, restricts results to icons released to the public domain.
          required: false
          schema:
            type: boolean
            default: false
        - name: thumbnail_size
          in: query
          description: Pixel dimension for returned thumbnail URLs.
          required: false
          schema:
            type: integer
            enum: [42, 84, 200]
            default: 84
        - name: blacklist
          in: query
          description: When true, applies the client's configured blocklist to results.
          required: false
          schema:
            type: boolean
            default: false
        - name: include_svg
          in: query
          description: When true, includes raw SVG markup in each icon result.
          required: false
          schema:
            type: boolean
            default: false
        - name: limit
          in: query
          description: Maximum number of icons returned per page.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: prev_page
          in: query
          description: Cursor token returned by a prior response for backward pagination.
          required: false
          schema:
            type: string
        - name: next_page
          in: query
          description: Cursor token returned by a prior response for forward pagination.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Paginated list of similar icons.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IconSearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - oauth1: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/icon/{icon_id}/download:
    get:
      operationId: downloadIcon
      summary: Download Icon
      description: >-
        Download a rendered icon in SVG or PNG format with optional hex-color
        recoloring and pixel sizing (PNG only). The response body is the icon
        binary; the content-type matches the requested filetype.
      tags:
        - Icon
      parameters:
        - $ref: '#/components/parameters/IconId'
        - name: color
          in: query
          description: >-
            Hexadecimal color value (without leading `#`) used to recolor the
            icon. Defaults to the icon's original color.
          required: false
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{6}$'
          example: ff5733
        - name: filetype
          in: query
          description: Output file format.
          required: false
          schema:
            type: string
            enum: [svg, png]
            default: svg
          example: png
        - name: size
          in: query
          description: >-
            PNG pixel dimension (20-1200). Ignored for SVG downloads which scale
            infinitely.
          required: false
          schema:
            type: integer
            minimum: 20
            maximum: 1200
            default: 200
          example: 512
      responses:
        '200':
          description: Rendered icon binary.
          content:
            image/svg+xml:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - oauth1: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
  /v2/collection:
    get:
      operationId: searchCollections
      summary: Search Collections
      description: >-
        Search curated icon collections (icon sets) by query term. Returns a
        paginated list of matching collections with metadata.
      tags:
        - Collection
      parameters:
        - name: query
          in: query
          description: Search term used to match collection titles, tags, and descriptions.
          required: true
          schema:
            type: string
          example: weather
        - name: blacklist
          in: query
          description: When true, applies the client's configured blocklist to results.
          required: false
          schema:
            type: boolean
            default: false
        - name: limit
          in: query
          description: Maximum number of collections returned per page.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: prev_page
          in: query
          description: Cursor token returned by a prior response for backward pagination.
          required: false
          schema:
            type: string
        - name: next_page
          in: query
          description: Cursor token returned by a prior response for forward pagination.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Paginated collection search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionSearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - oauth1: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/collection/{collection_id}:
    get:
      operationId: getCollection
      summary: Get Collection
      description: Retrieve a single icon collection with full metadata and member icons.
      tags:
        - Collection
      parameters:
        - $ref: '#/components/parameters/CollectionId'
        - name: blacklist
          in: query
          description: When true, returns 404 if the collection is on the client's blocklist.
          required: false
          schema:
            type: boolean
            default: false
        - name: thumbnail_size
          in: query
          description: Pixel dimension for returned thumbnail URLs.
          required: false
          schema:
            type: integer
            enum: [42, 84, 200]
            default: 84
        - name: include_svg
          in: query
          description: When true, includes raw SVG markup in each member icon.
          required: false
          schema:
            type: boolean
            default: false
        - name: limit
          in: query
          description: Maximum number of member icons returned per page.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: prev_page
          in: query
          description: Cursor token returned by a prior response for backward pagination.
          required: false
          schema:
            type: string
        - name: next_page
          in: query
          description: Cursor token returned by a prior response for forward pagination.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Collection details and member icons.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - oauth1: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/client/usage:
    get:
      operationId: getUsage
      summary: Get Client Usage
      description: >-
        Return the calling client key's current usage and limits for the hourly,
        daily, and monthly windows.
      tags:
        - Usage
      responses:
        '200':
          description: Current usage and limit snapshot.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - oauth1: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/client/blacklist:
    get:
      operationId: getBlocklist
      summary: Get Client Blocklist
      description: >-
        Return the current blocklist for the calling client key, including
        blocked icon IDs, collection IDs, terms, and phrases. Results are
        cached for 10 minutes.
      tags:
        - Blocklist
      responses:
        '200':
          description: Current blocklist contents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlocklistResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - oauth1: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/client/blacklist/id:
    post:
      operationId: addBlocklistIds
      summary: Add Blocklist IDs
      description: >-
        Add icon IDs or collection IDs to the client blocklist. Maximum 1,000
        IDs per request for paid tiers and 5 for free trial accounts.
      tags:
        - Blocklist
      parameters:
        - name: type
          in: query
          description: Type of identifier being blocked.
          required: false
          schema:
            type: string
            enum: [icon, collection]
            default: icon
      requestBody:
        description: Blocklist identifiers to add or overwrite.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlocklistIdRequest'
      responses:
        '200':
          description: Updated blocklist contents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlocklistResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - oauth1: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/client/blacklist/term:
    post:
      operationId: addBlocklistTerms
      summary: Add Blocklist Terms
      description: >-
        Add terms and phrases to the client blocklist. Maximum 1,000 terms per
        request for paid tiers and 5 for free trial accounts.
      tags:
        - Blocklist
      requestBody:
        description: Blocklist terms and phrases to add or overwrite.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlocklistTermRequest'
      responses:
        '200':
          description: Updated blocklist contents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlocklistResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - oauth1: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  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/
  parameters:
    IconId:
      name: icon_id
      in: path
      description: Numeric identifier of the icon.
      required: true
      schema:
        type: integer
        minimum: 1
      example: 1234567
    CollectionId:
      name: collection_id
      in: path
      description: Numeric identifier of the collection.
      required: true
      schema:
        type: integer
        minimum: 1
      example: 98765
  responses:
    Unauthorized:
      description: Missing or invalid OAuth 1.0a credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested icon, collection, or resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request was malformed or violated a documented limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: The hourly, daily, or monthly request quota has been exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Icon:
      type: object
      description: A single icon in the Noun Project library.
      properties:
        id:
          type: integer
          description: Numeric identifier of the icon.
          example: 1234567
        attribution:
          type: string
          description: Required attribution string when the icon is not public domain.
          example: rocket by Jane Smith from Noun Project
        attribution_preview_url:
          type: string
          format: uri
          description: URL to a rendered attribution image suitable for design overlays.
          example: https://static.thenounproject.com/png/1234567-attribution.png
        creator:
          $ref: '#/components/schemas/IconCreator'
        date_uploaded:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the icon was uploaded.
          example: '2024-08-15T13:45:00Z'
        is_active:
          type: boolean
          description: Whether the icon is currently active and available for download.
          example: true
        is_public_domain:
          type: boolean
          description: Whether the icon has been released into the public domain.
          example: false
        license_description:
          type: string
          description: Human-readable license summary.
          example: creative-commons-attribution
        permalink:
          type: string
          format: uri
          description: Canonical URL for the icon on thenounproject.com.
          example: https://thenounproject.com/icon/1234567/
        preview_url:
          type: string
          format: uri
          description: URL for the default-size preview image.
          example: https://static.thenounproject.com/png/1234567-200.png
        preview_url_42:
          type: string
          format: uri
          description: URL for the 42-pixel thumbnail.
          example: https://static.thenounproject.com/png/1234567-42.png
        preview_url_84:
          type: string
          format: uri
          description: URL for the 84-pixel thumbnail.
          example: https://static.thenounproject.com/png/1234567-84.png
        preview_url_200:
          type: string
          format: uri
          description: URL for the 200-pixel thumbnail.
          example: https://static.thenounproject.com/png/1234567-200.png
        icon_url:
          type: string
          format: uri
          description: Direct URL to the SVG asset (when include_svg is not used).
          example: https://static.thenounproject.com/svg/1234567.svg
        svg:
          type: string
          description: Inline SVG markup when include_svg=true was requested.
          example: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path d="..."/></svg>
        style:
          type: string
          description: Visual style classification of the icon.
          enum: [solid, line]
          example: solid
        line_weight:
          type: integer
          description: Line weight in pixels at 512px rendering (line-style icons only).
          minimum: 1
          maximum: 60
          example: 4
        tags:
          type: array
          description: Search tags applied to the icon.
          items:
            $ref: '#/components/schemas/Tag'
        term:
          type: string
          description: Primary search term used to discover the icon.
          example: rocket
        term_slug:
          type: string
          description: URL-safe version of the term.
          example: rocket
        year_published:
          type: integer
          description: Year the icon was first published.
          example: 2024
        royalty_free_license:
          type: boolean
          description: Whether the icon is included under the royalty-free license.
          example: true
        nsfw:
          type: boolean
          description: Whether the icon has been flagged not-safe-for-work.
          example: false
        sponsor_id:
          type: integer
          nullable: true
          description: Identifier of the sponsoring brand if any.
          example: null
        thumbnail_url:
          type: string
          format: uri
          description: Thumbnail URL at the requested thumbnail_size.
          example: https://static.thenounproject.com/png/1234567-200.png
      required:
        - id
        - permalink
    IconCreator:
      type: object
      description: The creator of an icon.
      properties:
        id:
          type: integer
          description: Numeric identifier of the creator.
          example: 4321
        username:
          type: string
          description: URL-safe username of the creator.
          example: jsmith
        name:
          type: string
          description: Display name of the creator.
          example: Jane Smith
        permalink:
          type: string
          format: uri
          description: Canonical URL for the creator profile.
          example: https://thenounproject.com/jsmith/
        location:
          type: string
          description: Free-text location reported by the creator.
          example: Brooklyn, NY
        bio:
          type: string
          description: Creator's profile bio.
          example: Designer focused on space exploration icons.
        avatar_url:
          type: string
          format: uri
          description: URL to the creator's avatar image.
          example: https://static.thenounproject.com/avatars/4321.png
      required:
        - id
        - username
    Tag:
      type: object
      description: A single search tag applied to an icon or collection.
      properties:
        id:
          type: integer
          description: Numeric identifier of the tag.
          example: 999
        slug:
          type: string
          description: URL-safe slug of the tag.
          example: spaceship
      required:
        - id
        - slug
    Collection:
      type: object
      description: A curated icon collection (icon set).
      properties:
        id:
          type: integer
          description: Numeric identifier of the collection.
          example: 98765
        slug:
          type: string
          description: URL-safe slug of the collection.
          example: weather-icons
        name:
          type: string
          description: Display name of the collection.
          example: Weather Icons
        description:
          type: string
          description: Marketing description of the collection.
          example: A complete weather iconography set covering conditions and forecasts.
        permalink:
          type: string
          format: uri
          description: Canonical URL for the collection on thenounproject.com.
          example: https://thenounproject.com/collection/98765/
        preview_url:
          type: string
          format: uri
          description: Cover image URL for the collection.
          example: https://static.thenounproject.com/collections/98765-cover.png
        creator:
          $ref: '#/components/schemas/IconCreator'
        date_created:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the collection was created.
          example: '2024-04-12T10:00:00Z'
        date_updated:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last collection update.
          example: '2024-09-30T18:22:00Z'
        is_published:
          type: boolean
          description: Whether the collection is published and discoverable.
          example: true
        icon_count:
          type: integer
          description: Number of icons currently in the collection.
          example: 32
        tags:
          type: array
          description: Search tags applied to the collection.
          items:
            $ref: '#/components/schemas/Tag'
        icons:
          type: array
          description: Member icons returned when retrieving a collection by ID.
          items:
            $ref: '#/components/schemas/Icon'
      required:
        - id
        - name
        - permalink
    IconSearchResponse:
      type: object
      description: Paginated icon search results.
      properties:
        icons:
          type: array
          description: Icons matching the search criteria.
          items:
            $ref: '#/components/schemas/Icon'
        generated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the response was generated.
          example: '2026-05-28T14:00:00Z'
        total:
          type: integer
          description: Total number of icons matching the search.
          example: 4321
        next_page:
          type: string
          nullable: true
          description: Cursor token for the next page of results.
          example: eyJsYXN0X2lkIjoxMjM0NTY3fQ==
        prev_page:
          type: string
          nullable: true
          description: Cursor token for the previous page of results.
          example: null
      required:
        - icons
    IconResponse:
      type: object
      description: Single icon response wrapper.
      properties:
        icon:
          $ref: '#/components/schemas/Icon'
        generated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the response was generated.
          example: '2026-05-28T14:00:00Z'
      required:
        - icon
    CollectionSearchResponse:
      type: object
      description: Paginated collection search results.
      properties:
        collections:
          type: array
          description: Collections matching the search criteria.
          items:
            $ref: '#/components/schemas/Collection'
        generated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the response was generated.
          example: '2026-05-28T14:00:00Z'
        total:
          type: integer
          description: Total number of collections matching the search.
          example: 187
        next_page:
          type: string
          nullable: true
          description: Cursor token for the next page of results.
          example: eyJsYXN0X2lkIjo5ODc2NX0=
        prev_page:
          type: string
          nullable: true
          description: Cursor token for the previous page of results.
          example: null
      required:
        - collections
    CollectionResponse:
      type: object
      description: Single collection response wrapper.
      properties:
        collection:
          $ref: '#/components/schemas/Collection'
        generated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the response was generated.
          example: '2026-05-28T14:00:00Z'
      required:
        - collection
    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
    Usage:
      type: object
      description: API key usage and quota information.
      properties:
        hourly:
          $ref: '#/components/schemas/UsageWindow'
        daily:
          $ref: '#/components/schemas/UsageWindow'
        monthly:
          $ref: '#/components/schemas/UsageWindow'
    UsageWindow:
      type: object
      description: Usage statistics for a single time window.
      properties:
        service_calls_used:
          type: integer
          description: Non-icon API calls consumed in this window.
          example: 245
        service_calls_limit:
          type: integer
          description: Maximum non-icon API calls allowed in this window.
          example: 1000
        icon_calls_used:
          type: integer
          description: Icon-specific calls consumed in this window.
          example: 38
        icon_calls_limit:
          type: integer
          description: Maximum icon-specific calls allowed in this window.
          example: 150
        period_start:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when this window started.
          example: '2026-05-28T00:00:00Z'
        period_end:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when this window ends.
          example: '2026-05-29T00:00:00Z'
    UsageResponse:
      type: object
      description: Wrapper for the client usage response.
      properties:
        usage:
          $ref: '#/components/schemas/Usage'
        generated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the response was generated.
          example: '2026-05-28T14:00:00Z'
      required:
        - usage
    Blocklist:
      type: object
      description: The current blocklist for a client key.
      properties:
        icon_ids:
          type: array
          description: Blocked icon identifiers.
          items:
            type: integer
          example: [12345, 67890]
        collection_ids:
          type: array
          description: Blocked collection identifiers.
          items:
            type: integer
          example: [98765]
        terms:
          type: array
          description: Blocked terms and phrases.
          items:
            type: string
          example: [violence, weapon]
        cached_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the blocklist was last cached.
          example: '2026-05-28T13:55:00Z'
    BlocklistResponse:
      type: object
      description: Wrapper for the client blocklist response.
      properties:
        blacklist:
          $ref: '#/components/schemas/Blocklist'
        generated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the response was generated.
          example: '2026-05-28T14:00:00Z'
      required:
        - blacklist
    BlocklistIdRequest:
      type: object
      description: Request body for adding icon or collection IDs to the blocklist.
      properties:
        blacklist:
          type: array
          description: Identifiers to add to the blocklist.
          items:
            type: integer
          minItems: 1
          maxItems: 1000
          example: [12345, 67890]
        overwrite:
          type: boolean
          description: When true, replaces the existing blocklist for this type entirely.
          default: false
          example: false
      required:
        - blacklist
    BlocklistTermRequest:
      type: object
      description: Request body for adding terms or phrases to the blocklist.
      properties:
        blacklist:
          type: array
          description: Terms and phrases to add to the blocklist.
          items:
            type: string
          minItems: 1
          maxItems: 1000
          example: [violence, weapon]
        overwrite:
          type: boolean
          description: When true, replaces the existing term blocklist entirely.
          default: false
          example: false
      required:
        - blacklist
    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
security:
  - oauth1: []