Documentation
Rest API
Endpoints
Endpoints
Base url: https://v1.nekosapi.com/api
⚠️
The base URL will be moved to https://api.nekosapi.com/v1 in a few days.
If the endpoint stops responding, check the new base endpoint.
GET /
GET/
Information
Returns information about the API such as it's endpoints and version.
Parameters
No parameters
Responses
200: Success
The request was successful.
application/json12 lines
{
"data": [
"/",
"/stats",
...
],
"meta": {
"version": "v1.4.2",
"baseApiRoute": "/api"
},
"success": true
}429: Too many requests
You have made too many requests.
API Wrappers
No wrapper support.
GET /stats
GET/stats
Get current API statistics
Get the current API statistics.
Parameters
No parameters
Responses
200: Success
The request was successful.
application/json18 lines
{
"data": {
"images": {
"count": 2890,
"nsfw": {
"nsfw": 9,
"questionable": 19,
"sfw": 2862
},
...
},
"artists": {
"count": 1
},
...
},
"success": true
}429: Too many requests
You have made too many requests.
API Wrappers
No wrapper support.
GET /token
This endpoint requires an access token. You can read more about why we have protected endpoints here.
GET/token
Get token information
Get information about the current access token.
Parameters
Authorization*
token (header)
The access token.
Responses
200: Success
The request was successful.
application/json11 lines
{
"data": {
"owner": "xxxxxx (Discord ID: xxxxxxxxxxxxxxxxxx)",
"purpose": "xxxxxxxxxxxx",
"scopes": ["image:list", "image:custom-expiry:86400"],
"issuedBy": "xxxxxx (Discord ID: xxxxxxxxxxxxxxxxxx)",
"createdAt": "2023-01-01T00:00:00.000Z",
"expires": "2023-01-01T00:00:00.000Z"
},
"success": true
}401: Unauthorized
You have not provided a token.
401: Invalid token
The token provided is not a valid token.
429: Too many requests
You have made too many requests.
API Wrappers
No wrapper support.
GET /image
This is the only endpoint (ignoring /token) that requires authorization.
You can read more about why we do this here.
GET/image
Get all images
Returns a list of all available images.
Parameters
Authorization*
token (header)
The access token.
limit
number
The maximum amount of images to get. (max. 25)
offset
number
The number of images to skip.
expiry
number
The amount of time in seconds the link will be valid (until expiry) (requires auth)
Responses
200: Success
The request was successful.
application/json58 lines
{
"data": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"url": "https://example.com/assets/xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png",
"artist": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"source": {
"name": "xxxxxxx",
"url": "https://example.com/xxxxxxx"
},
"nsfw": "sfw",
"categories": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "xxxxxxx",
"description": "xxxxxxxxxxxxxxxxxx",
"nsfw": false,
"createdAt": "2021-01-01T00:00:00.000Z"
}
],
"characters": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "xxxxxxx",
"description": "xxxxxxxxxxxxxxxxxx",
"source": "xxxxxxxxx",
"gender": "xxxxxx",
"ages": [
16,
17
],
"birth_date": "xxxx xxxx",
"nationality": "xxxxxxxxx",
"occupations": [
"xxxx xxxxxx",
"xxxxxx xxxxxxx xxxxxxxxxxx"
],
"createdAt": "2021-01-01T00:00:00.000Z"
}
],
"createdAt": "2021-01-01T00:00:00.000Z",
"meta": {
"eTag": "xxxxxxxxxxxxxxxxxxxxx",
"size": 6336807,
"mimetype": "image/png",
"color": "#ffffff",
"expires": "2021-01-01T00:00:00.000Z",
"dimens": {
"width": 1024,
"height": 1024,
"aspectRatio": "1:1",
"orientation": "landscape"
}
}
}
],
"success": true
}400: Invalid limit
The limit provided is not a number between 1 and 25.
400: Invalid offset
The offset provided is not a number greater than 0.
400: Invalid expiry
The provided custom expiry time is not a number greater than 30.
401: Unauthorized
You have not provided a token.
401: Invalid token
The token provided is not a valid token.
403: Missing permission
The access token provided has not got permission to list all images.
403: Missing permission
The access token provided has not got permission to set a custom image expiry time.
403: Missing permission
The custom expiry time is greater than what allowed by the token.
429: Too many requests
You have made too many requests.
API Wrappers
No wrapper support.
GET /image/random
GET/image/random
Get random images
Returns one or more random images from the specified category.
Parameters
categories
list of strings
The category names that the image should have.
limit
number
The maximum amount of images to get. (max. 25)
expiry
number
The amount of time in seconds the link will be valid (until expiry) (requires auth)
Responses
200: Success
The request was successful.
application/json58 lines
{
"data": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"url": "https://example.com/assets/xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png",
"artist": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"source": {
"name": "xxxxxxx",
"url": "https://example.com/xxxxxxx"
},
"nsfw": "sfw",
"categories": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "xxxxxxx",
"description": "xxxxxxxxxxxxxxxxxx",
"nsfw": false,
"createdAt": "2021-01-01T00:00:00.000Z"
}
],
"characters": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "xxxxxxx",
"description": "xxxxxxxxxxxxxxxxxx",
"source": "xxxxxxxxx",
"gender": "xxxxxx",
"ages": [
16,
17
],
"birth_date": "xxxx xxxx",
"nationality": "xxxxxxxxx",
"occupations": [
"xxxx xxxxxx",
"xxxxxx xxxxxxx xxxxxxxxxxx"
],
"createdAt": "2021-01-01T00:00:00.000Z"
}
],
"createdAt": "2021-01-01T00:00:00.000Z",
"meta": {
"eTag": "xxxxxxxxxxxxxxxxxxxxx",
"size": 6336807,
"mimetype": "image/png",
"color": "#ffffff",
"expires": "2021-01-01T00:00:00.000Z",
"dimens": {
"width": 1024,
"height": 1024,
"aspectRatio": "1:1",
"orientation": "landscape"
}
}
}
],
"success": true
}400: Invalid categories
One or more categories selected do not exist.
400: Invalid limit
The specified limit is not a number between 1 and 25.
400: Invalid expiry
The provided custom expiry time is not a number greater than 30.
401: Invalid token
The token provided is not a valid token.
403: Missing permission
The access token provided has not got permission to set a custom image expiry time.
403: Missing permission
The custom expiry time is greater than what allowed by the token.
429: Too many requests
You have made too many requests.
API Wrappers
PythonGET /image/{id}
GET/image/{id}
Get an image
Get an image by its ID.
Parameters
id*
uuid
The ID of the image to get.
expiry
number
The amount of time in seconds the link will be valid (until expiry) (requires auth)
Responses
200: Success
The request was successful.
application/json56 lines
{
"data": {
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"url": "https://example.com/assets/xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png",
"artist": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"source": {
"name": "xxxxxxx",
"url": "https://example.com/xxxxxxx"
},
"nsfw": "sfw",
"categories": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "xxxxxxx",
"description": "xxxxxxxxxxxxxxxxxx",
"nsfw": false,
"createdAt": "2021-01-01T00:00:00.000Z"
}
],
"characters": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "xxxxxxx",
"description": "xxxxxxxxxxxxxxxxxx",
"source": "xxxxxxxxx",
"gender": "xxxxxx",
"ages": [
16,
17
],
"birth_date": "xxxx xxxx",
"nationality": "xxxxxxxxx",
"occupations": [
"xxxx xxxxxx",
"xxxxxx xxxxxxx xxxxxxxxxxx"
],
"createdAt": "2021-01-01T00:00:00.000Z"
}
],
"createdAt": "2021-01-01T00:00:00.000Z",
"meta": {
"eTag": "xxxxxxxxxxxxxxxxxxxxx",
"size": 6336807,
"mimetype": "image/png",
"color": "#ffffff",
"expires": "2021-01-01T00:00:00.000Z",
"dimens": {
"width": 1024,
"height": 1024,
"aspectRatio": "1:1",
"orientation": "landscape"
}
}
},
"success": true
}400: Invalid ID
The provided ID is not a valid UUID.
401: Invalid token
The token provided is invalid.
403: Missing permission
The access token provided has not got permission to set a custom image expiry time.
403: Missing permission
The custom expiry time is greater than what allowed by the token.
404: Not found
Could not find image with the provided ID.
429: Too many requests
You have made too many requests.
API Wrappers
GET /artist
GET/artist
Search for an artist
Search for an artist/get all artists.
Parameters
limit
number
The maximum number of images to get.
offset
number
The number of images to skip.
search
string
A search query (formatted as specified in the reference page).
Responses
200: Success
The request was successful.
application/json11 lines
{
"data": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "xxxxxxx",
"url": "https://example.com/xxxxxxx"
},
...
],
"success": true
}400: Invalid limit
The limit provided is not a number between 1 and 25.
400: Invalid offset
The offset provided is not a number greater than 0.
400: Invalid search query
The search query provided is longer than 50 characters.
401: Invalid token
The token provided is invalid.
429: Too many requests
You have made too many requests.
API Wrappers
GET /artist/{id}
GET/artist/{id}
Get an artist
Get an artist by it's ID.
Parameters
id*
uuid
The artist's ID.
Responses
200: Success
The request was successful.
application/json9 lines
{
"data": {
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "xxxxxxx",
"url": "https://example.com/xxxxxxx",
"images": 12
},
"success": true
}400: Invalid ID
The provided ID is not a valid UUID.
401: Invalid token
The token provided is invalid.
404: Not found
Could not find an artist with the provided ID.
429: Too many requests
You have made too many requests.
API Wrappers
GET /artist/{id}/images
GET/artist/{id}/images
Get an artist's images
Get all images by an artist.
Parameters
id*
uuid
The artist's ID.
limit
number
The maximum amount of images to get.
offset
number
The number of images to skip.
expiry
number
The amount of time in seconds the link will be valid (until expiry) (requires auth)
Responses
200: Success
The request was successful.
application/json57 lines
{
"data": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"url": "https://example.com/assets/xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png",
"artist": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"source": {
"name": "xxxxxxx",
"url": "https://example.com/xxxxxxx"
},
"nsfw": "sfw",
"categories": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "xxxxxxx",
"description": "xxxxxxxxxxxxxxxxxx",
"nsfw": false,
"createdAt": "2021-01-01T00:00:00.000Z"
}
],
"characters": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "xxxxxxx",
"description": "xxxxxxxxxxxxxxxxxx",
"source": "xxxxxxxxx",
"gender": "xxxxxx",
"ages": [
16,
17
],
"birth_date": "xxxx xxxx",
"nationality": "xxxxxxxxx",
"occupations": [
"xxxx xxxxxx",
"xxxxxx xxxxxxx xxxxxxxxxxx"
],
"createdAt": "2021-01-01T00:00:00.000Z"
}
],
"createdAt": "2021-01-01T00:00:00.000Z",
"meta": {
"eTag": "xxxxxxxxxxxxxxxxxxxxx",
"size": 6336807,
"mimetype": "image/png",
"color": "#ffffff",
"expires": "2021-01-01T00:00:00.000Z",
"dimens": {
"width": 1024,
"height": 1024,
"orientation": "landscape"
}
}
}
],
"success": true
}400: Invalid ID
The provided ID is not a valid UUID.
400: Invalid limit
The limit provided is not a number between 1 and 25.
400: Invalid offset
The offset provided is not a number greater than 0.
400: Invalid expiry
The provided custom expiry time is not a number greater than 30.
401: Invalid token
The token provided is invalid.
403: Missing permission
The access token provided has not got permission to set a custom image expiry time.
403: Missing permission
The custom expiry time is greater than what allowed by the token.
404: Not found
Could not find an artist with the provided ID.
429: Too many requests
You have made too many requests.
API Wrappers
GET /character
GET/character
Search for a character
Search for a character or get all available characters.
Parameters
limit
number
The maximum amount of characters to get.
offset
number
The amount of characters to skip.
search
string
A search query (formatted as specified in the reference page).
Responses
200: Success
The request was successful.
application/json23 lines
{
"data": [
{
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "xxxxxxx",
"description": "xxxxxxxxxxxxxxxxxx",
"source": "xxxxxxxxx",
"gender": "xxxxxx",
"ages": [
16,
17
],
"birth_date": "xxxx xxxx",
"nationality": "xxxxxxxxx",
"occupations": [
"xxxx xxxxxx",
"xxxxxx xxxxxxx xxxxxxxxxxx"
],
"createdAt": "2021-01-01T00:00:00.000Z"
}
],
"success": true
}400: Invalid limit
The limit provided is not a number between 1 and 25.
400: Invalid offset
The offset provided is not a number greater than 0.
400: Invalid search query
The search query provided is longer than 50 characters.
401: Invalid token
The token provided is invalid.
429: Too many requests
You have made too many requests.
API Wrappers
GET /character/{id}
GET/character/{id}
Get a character
Get a character by its ID.
Parameters
id*
uuid
The ID of the character to get.
Responses
200: Success
The request was successful.
application/json22 lines
{
"data": {
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "xxxxxxx",
"description": "xxxxxxxxxxxxxxxxxx",
"source": "xxxxxxxxx",
"gender": "xxxxxx",
"ages": [
16,
17
],
"birth_date": "xxxx xxxx",
"nationality": "xxxxxxxxx",
"occupations": [
"xxxx xxxxxx",
"xxxxxx xxxxxxx xxxxxxxxxxx"
],
"createdAt": "2021-01-01T00:00:00.000Z",
"images": 3
},
"success": true
}400: Invalid ID
The provided ID is not a valid UUID.
404: Not found
Could not find a character with the provided ID.
429: Too many requests
You have made too many requests.
API Wrappers
GET /category
GET/category
Search for a category
Search for a category or get all available categories.
Parameters
limit
number
The maximum amount of categories to get.
offset
number
The amount of categories to skip.
search
string
A search query (formatted as specified in the reference page).
Responses
200: Success
The request was successful.
application/json13 lines
{
'data': [
{
'id': 'xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
'name': 'xxxxxxx',
'description': 'xxxxxxxxxxxxxxxxxx',
'nsfw': false,
'createdAt': '2021-01-01T00:00:00.000Z',
},
...
],
'success': true,
}400: Invalid limit
The limit provided is not a number between 1 and 25.
400: Invalid offset
The offset provided is not a number greater than 0.
400: Invalid search query
The search query provided is longer than 50 characters.
401: Invalid token
The token provided is invalid.
429: Too many requests
You have made too many requests.
API Wrappers
GET /category/{id}
Get a category by its ID.
GET/category/{id}
Get a category
Get a category by its ID.
Parameters
id*
uuid
The ID of the category to get.
Responses
200: Success
The request was successful.
application/json11 lines
{
"data": {
"id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "xxxxxxx",
"description": "xxxxxxxxxxxxxxxxxx",
"nsfw": false,
"createdAt": "2021-01-01T00:00:00.000Z",
"images": 12
},
"success": true
}400: Invalid ID
The provided ID is not a valid UUID.
401: Invalid token
The token provided is invalid.
404: Not found
Could not find a category with the provided ID.
429: Too many requests
You have made too many requests.
API Wrappers