DocumentationMCPStatusLicensePricing
v1.0.0
OpenAPI 2.0

Illustrations API

Find more info here
Icons8 Team
Terms of Service

Public API for accessing illustrations, styles, tags, and categories

Server:https://api-illustrations.icons8.com/api
Client Libraries
Node.js undici

Illustrations

​

Search and list illustrations, get an illustration by id and its high-resolution file.

Illustrations Operations

Search illustrations

​

Search illustrations by query

Query Parameters

  • query
    Type: string
    required

    Text search query

  • styles
    Type: array of string

    Coma separated styles

  • type
    Type: "illustration" or "component"enum
  • mediaFormat
    Type: "png" or "svg"enum

    Filter by media resources

  • orderBy
    Type: "relevant" or "random"enum
  • locale
    Type: stringenum

    Query and result language

    values
    enrufrdeitjpesbrcnko
  • page
    Type: integerFormat: int32
    min:  
    1

    Page number

  • perPage
    Type: integerFormat: int32
    min:  
    1
    max:  
    100

    Number of results per page. Max: 100

  • fields
    Type: string

    Return only specified fields. Example: "id,mediaResources,urls(thumb)". Please request only needed fields.

Responses

  • application/json
  • application/json
  • application/json
Request Example for get/v2/illustrations/search
import { request } from 'undici'

const { statusCode, body } = await request('https://api-illustrations.icons8.com/api/v2/illustrations/search?query=eco&type=illustration&mediaFormat=png&orderBy=relevant&locale=en&page=1&perPage=10&fields=id%2CmediaResources%2Curls', {
  headers: {
    'Api-Key': 'YOUR_SECRET_TOKEN'
  }
})

{
  "total": 8709,
  "illustrations": [
    {
      "id": "5d1a04e39e78e00015a598f3",
      "free": false,
      "type": "illustration",
      "heading": "Solar panels as eco technology",
      "description": null,
      "author": {
        "icons8Id": "IkN6IH6CvAcL",
        "name": "Sara Maese",
        "url": "http://www.saramaese.com/"
      },
      "styles": [
        "Pluto"
      ],
      "categories": [
        "Objects",
        "Building",
        "Ecology",
        "Greentech",
        "People",
        "Technologies",
        "Web Element",
        "Waiting"
      ],
      "tags": [
        "waiting",
        "garden",
        "process",
        "technologies",
        "watering",
        "eco",
        "nature",
        "gardening",
        "solar panels",
        "watering can",
        "house",
        "gardener",
        "watering pot",
        "solar battery",
        "house clipart",
        "solar",
        "closer to nature",
        "watering plant",
        "nature clipart",
        "watering flower",
        "eco tech",
        "eco technology",
        "working in nature",
        "working in garden"
      ],
      "mediaResources": [
        "svg",
        "png",
        "png-hd"
      ],
      "urls": {
        "thumb": {
          "width": 368,
          "height": 296,
          "url": "https://ouch-prod-var-cdn.icons8.com/wu/illustrations/thumbs/2uDbt6xTreFJN8K5.webp"
        },
        "small": {
          "width": 456,
          "height": 367,
          "url": "https://ouch-prod-var-cdn.icons8.com/xy/illustrations/previews/NwEnXWnDzkgp8F0z.webp"
        },
        "medium": {
          "width": 912,
          "height": 734,
          "url": "https://ouch-prod-var-cdn.icons8.com/mk/illustrations/previews/-u5nFI3b0To9X_Cx.webp"
        },
        "large": {
          "width": 1133,
          "height": 912,
          "url": "https://ouch-prod-var-cdn.icons8.com/bn/illustrations/thumbs/example.png"
        }
      },
      "createdAt": 1561986276424
    }
  ]
}

Paged illustrations response

List illustrations

​

List illustrations with filters

Query Parameters

  • type
    Type: "illustration" or "component"enum
  • mediaFormat
    Type: "png" or "svg"enum

    Filter by media resources

  • author
    Type: string
  • styles
    Type: array of string

    Coma separated styles

  • categories
    Type: array of string

    Coma separated categories

  • tags
    Type: array of string

    Coma separated tags

  • orderBy
    Type: "latest" or "oldest" or "random"enum
  • locale
    Type: stringenum

    Query and result language

    values
    enrufrdeitjpesbrcnko
  • page
    Type: integerFormat: int32
    min:  
    1

    Page number

  • perPage
    Type: integerFormat: int32
    min:  
    1
    max:  
    100

    Number of results per page. Max: 100

  • fields
    Type: string

    Return only specified fields. Example: "id,mediaResources,urls(thumb)". Please request only needed fields.

Responses

  • application/json
  • application/json
Request Example for get/v2/illustrations
import { request } from 'undici'

const { statusCode, body } = await request('https://api-illustrations.icons8.com/api/v2/illustrations?type=illustration&mediaFormat=png&orderBy=latest&locale=en&page=1&perPage=10&fields=id%2CmediaResources%2Curls', {
  headers: {
    'Api-Key': 'YOUR_SECRET_TOKEN'
  }
})

{
  "total": 8709,
  "illustrations": [
    {
      "id": "5d1a04e39e78e00015a598f3",
      "free": false,
      "type": "illustration",
      "heading": "Solar panels as eco technology",
      "description": null,
      "author": {
        "icons8Id": "IkN6IH6CvAcL",
        "name": "Sara Maese",
        "url": "http://www.saramaese.com/"
      },
      "styles": [
        "Pluto"
      ],
      "categories": [
        "Objects",
        "Building",
        "Ecology",
        "Greentech",
        "People",
        "Technologies",
        "Web Element",
        "Waiting"
      ],
      "tags": [
        "waiting",
        "garden",
        "process",
        "technologies",
        "watering",
        "eco",
        "nature",
        "gardening",
        "solar panels",
        "watering can",
        "house",
        "gardener",
        "watering pot",
        "solar battery",
        "house clipart",
        "solar",
        "closer to nature",
        "watering plant",
        "nature clipart",
        "watering flower",
        "eco tech",
        "eco technology",
        "working in nature",
        "working in garden"
      ],
      "mediaResources": [
        "svg",
        "png",
        "png-hd"
      ],
      "urls": {
        "thumb": {
          "width": 368,
          "height": 296,
          "url": "https://ouch-prod-var-cdn.icons8.com/wu/illustrations/thumbs/2uDbt6xTreFJN8K5.webp"
        },
        "small": {
          "width": 456,
          "height": 367,
          "url": "https://ouch-prod-var-cdn.icons8.com/xy/illustrations/previews/NwEnXWnDzkgp8F0z.webp"
        },
        "medium": {
          "width": 912,
          "height": 734,
          "url": "https://ouch-prod-var-cdn.icons8.com/mk/illustrations/previews/-u5nFI3b0To9X_Cx.webp"
        },
        "large": {
          "width": 1133,
          "height": 912,
          "url": "https://ouch-prod-var-cdn.icons8.com/bn/illustrations/thumbs/example.png"
        }
      },
      "createdAt": 1561986276424
    }
  ]
}

Paged illustrations response

Illustration by id

​

Get illustration by ID

Path Parameters

  • id
    Type: string
    required

    ID

Query Parameters

  • locale
    Type: stringenum

    Query and result language

    values
    enrufrdeitjpesbrcnko
  • fields
    Type: string

    Return only specified fields. Example: "id,mediaResources,urls(thumb)". Please request only needed fields.

Responses

  • application/json
  • application/json
  • application/json
Request Example for get/v2/illustrations/{id}
import { request } from 'undici'

const { statusCode, body } = await request('https://api-illustrations.icons8.com/api/v2/illustrations/5d1a04e39e78e00015a598f3?locale=en&fields=id%2CmediaResources%2Curls', {
  headers: {
    'Api-Key': 'YOUR_SECRET_TOKEN'
  }
})

{
  "id": "5d1a04e39e78e00015a598f3",
  "free": false,
  "type": "illustration",
  "heading": "Solar panels as eco technology",
  "description": null,
  "author": {
    "icons8Id": "IkN6IH6CvAcL",
    "name": "Sara Maese",
    "url": "http://www.saramaese.com/"
  },
  "styles": [
    "Pluto"
  ],
  "categories": [
    "Objects",
    "Building",
    "Ecology",
    "Greentech",
    "People",
    "Technologies",
    "Web Element",
    "Waiting"
  ],
  "tags": [
    "waiting",
    "garden",
    "process",
    "technologies",
    "watering",
    "eco",
    "nature",
    "gardening",
    "solar panels",
    "watering can",
    "house",
    "gardener",
    "watering pot",
    "solar battery",
    "house clipart",
    "solar",
    "closer to nature",
    "watering plant",
    "nature clipart",
    "watering flower",
    "eco tech",
    "eco technology",
    "working in nature",
    "working in garden"
  ],
  "mediaResources": [
    "svg",
    "png",
    "png-hd"
  ],
  "urls": {
    "thumb": {
      "width": 368,
      "height": 296,
      "url": "https://ouch-prod-var-cdn.icons8.com/wu/illustrations/thumbs/2uDbt6xTreFJN8K5.webp"
    },
    "small": {
      "width": 456,
      "height": 367,
      "url": "https://ouch-prod-var-cdn.icons8.com/xy/illustrations/previews/NwEnXWnDzkgp8F0z.webp"
    },
    "medium": {
      "width": 912,
      "height": 734,
      "url": "https://ouch-prod-var-cdn.icons8.com/mk/illustrations/previews/-u5nFI3b0To9X_Cx.webp"
    },
    "large": {
      "width": 1133,
      "height": 912,
      "url": "https://ouch-prod-var-cdn.icons8.com/bn/illustrations/thumbs/example.png"
    }
  },
  "createdAt": 1561986276424
}

Single illustration response

High-resolution illustration

​

Get high-resolution illustration asset. png is a 912 px preview, free for everyone. png-hd (the original png) and svg of a paid illustration need your Icons8 API key; without it the API answers 401.

Path Parameters

  • id
    Type: string
    required

    ID

Query Parameters

  • mediaFormat
    Type: "png" or "svg" or "png-hd"enum

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/v2/illustrations/{id}/hi-res
import { request } from 'undici'

const { statusCode, body } = await request('https://api-illustrations.icons8.com/api/v2/illustrations/5d1a04e39e78e00015a598f3/hi-res?mediaFormat=png', {
  headers: {
    'Api-Key': 'YOUR_SECRET_TOKEN'
  }
})

{
  "url": "https://ACCOUNT_ID.r2.cloudflarestorage.com/r2-ouch-prod-var/example.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=SIGNATURE",
  "width": 1133,
  "height": 912
}

High-resolution asset response

Styles (Collapsed)

​

List illustration styles. Use them as filters when you search or list illustrations.

Styles Operations

Tags (Collapsed)

​

List illustration tags. Use them as filters when you list illustrations.

Tags Operations

Categories (Collapsed)

​

Get the tree of illustration categories. Use them as filters when you list illustrations.

Categories Operations