Images

An API Key is not required for MOST endpoints of this service. See Shared Responses for common error responses.

Online Check

GET https://v2.yiff.rest/online

200: OK Success

{
  "success": true,
  "uptime": 0
}

List Categories

GET https://v2.yiff.rest/categories

200: OK Success

{
  "success": true,
  "data": {
    "enabled": [
      {
        "name": "Animals > Birb",
        "db": "animals.birb"
      }
      // (...)
    ],
    "disabled": [
      {
        "name": "Animals > Fox",
        "db": "animals.fox",
        "_comment": "Category has never had any content."
      }
      // (...)
    ]
  }
}

Get Information About A Category

GET https://v2.yiff.rest/categories/:db

Path Parameters

Name	Type	Description
db*	String	The "db" representation of the category (see GET /categories)

200: OK Success

{
  "success": true,
  "data": {
    "name": "Animals > Birb",
    "db": "animals.birb",
    "dir": "/app/public/V2/animals/birb",
    // _comment can also be present
    "disabled": false,
    "files": {
      "exists": true,
      "list": {
        "total": 65,
        "size": {
          "total": 107429688,
          "totalM": 102.453, // Mebibytes
          "average": 1652764.431,
          "averageM": 1.576 // Mebibytes
        },
        "types": {
        // mime types - none guaranteed
          "image/jpeg": 22,
          "image/gif": 6,
          "image/png": 37
        }
      }
    }
  }
}

404: Not Found Not Found

{
  "success": false,
  "error": {
    "message": "Category not found in list."
  },
  "code": 1030
}

Get Image

GET https://v2.yiff.rest/images/:id.json

Path Parameters

Name	Type	Description
id*	String	The ID of the image.

404: Not Found Not Found

{
  "success": false,
  "error": "No image was found with that id.",
  "code": 1040
}

200: OK Success

{
  "success": true,
  "data": {
    "artists": [].
    "sources": [],
    "width": 0,
    "height": 0,
    "url": "https://v2.yiff.media/{id}.{ext}",
    "yiffMediaURL": "https://v2.yiff.media/{id}.{ext}",
    "type": "{mime}",
    "name": "{name}.{ext}",
    "id": "{id}",
    "ext": "{ext}",
    "size": 0,
    "reportURL": null,
    "shortURL": "https://yiff.rocks/{id}",
    "category": "" // db format
  }
}

Get Random Image

GET https://v2.yiff.rest/:category

Path Parameters

Name	Type	Description
category*	String	The category, see GET /categories (db, replace periods with forward slashes)

Query Parameters

Name	Type	Description
amount	Number	The amount of images to request, between 1-5.
notes	String	If notes should be hidden. Use the literal string "disabled".
sizeLimit	Number	The maximum size of image to get, in powers of 2. Prefixes such as KB/MB can be used.

400: Bad Request Limit <1

{
  "success": false,
  "error": "Amount must be 1 or more.",
  "code": 1051
}

400: Bad Request Limit >5

{
  "success": false,
  "error": "Amount must be 5 or less.",
  "code": 1052
}

400: Bad Request No Results Found

{
  "success": false,
  "error": "No results were found. Try changing your search parameters.",
  "code": 1041
}

200: OK Success

// Notes:
// 0: null
// 1: This api host (api.furry.bot) is being removed on June 9th, 2021. Please migrate to https://yiff.rest.
// 2: We're moving to using subdomains for api versioning! e.g. https://v2.yiff.rest. They have the same functionality, just without the version in the path. The /V2 route will not be removed, but v3 and forward will only use the subdomain.
// 3: Hey, we see you aren't using an api key. They're free! To get one, join our support server (https://yiff.rest/support), and run the command "/apikey", you'll see how to use it there.
// 4: WARNING! This list is STATIC, it can be inaccurate! We recommended parsing the dot notation in https://v2.yiff.rest/categories instead of this!
// 5: Since images are getting bigger, we're adding a size limit parameter. Add ?sizeLimit=<size> to limit the size of images we provide you. We process sizes in powers of 2, not 10.
// 6: You can now hide these notes by setting the notes parameter to disabled. (ex: ?notes=disabled)
{
  "success": true",
  "$schema": "https://schema.yiff.rest/V2.json",
  "notes": [
    {
      "id": 0,
      "content": ""
    }
  ],
  "images": [
    {
      "artists": [].
      "sources": [],
      "width": 0,
      "height": 0,
      "url": "https://v2.yiff.media/{id}.{ext}",
      "type": "{mime}",
      "name": "{name}.{ext}",
      "id": "{id}",
      "ext": "{ext}",
      "size": 0,
      "reportURL": null,
      "shortURL": "https://yiff.rocks/{id}"
    }
  ]
}

400: Bad Request Invalid Response Type

{
  "success": false,
  "error": {
    "message": "invalid response type",
    "type": "client".
    "code": 1023
  }
}

500: Internal Server Error Internal Server Error

{
  "success": false,
  "error": "There was an internal error while attempting to perform that action.",
  "code": 0
}

404: Not Found Category Not Found

{
  "success": false,
  "error": "Category not found.",
  "code": 1030
}

Get Images Bulk

POST https://v2.yiff.rest/bulk

Get an arbitrary amount of images across many categories. This endpoint requires an api key, and is restricted to developer approval.

By default, a maximum of 100 images total can be fetched in one request. You can request your limit to be raised by contacting a developer.

Path Parameters

Name	Type	Description
sizeLimit	String	The maximum size of image to get, in powers of 2. Prefixes such as KB/MB can be used.

Request Body

Name	Type	Description
some.category*	Number	A map of category (in db format) to the amount of images. See List Categories for the list of categories.

200: OK Success

// a map of category (in db format) to the requested imagess
{
  "some.category": [
    {
      "artists": [].
      "sources": [],
      "width": 0,
      "height": 0,
      "url": "https://v2.yiff.media/{id}.{ext}",
      "type": "{mime}",
      "name": "{name}.{ext}",
      "id": "{id}",
      "ext": "{ext}",
      "size": 0,
      "reportURL": null,
      "shortURL": "https://yiff.rocks/{id}"
    }
  ]
}

400: Bad Request Invalid Body

{
  "success": false,
  "error": "Invalid body, or no categories specified.",
  "code": 1054
}

400: Bad Request Invalid Category

{
  "success": false,
  "error": "Invalid category specified: invalid.category",
  "code": 1055
}

400: Bad Request >Max Images Requested

{
  "success": false,
  "error": "Total amount of images requested is greater than {limit} ({total})",
  "code": 1056
}