JjalBot API Documentation

JjalBot provides a public REST API for searching and retrieving jjals (Korean meme images and GIFs). This API is designed for developers, AI agents, bots, and CLI tools.

Base URL

https://api.jjalbot.com

All endpoints return JSON responses.

Endpoints

Search Jjals

GET /jjals?text=<keyword>

Search for jjals by keyword. Uses text matching with automatic fallback to semantic (vector similarity) search when no exact matches are found.

Query Parameters

Parameter	Type	Required	Description
`text`	string	Yes	Search keyword (must be Korean)
`thumbnail`	boolean	No	If `true`, only return jjals with thumbnails

Example Request

curl "https://api.jjalbot.com/jjals?text=신나는"

Example Response

[
  {
    "id": 12345,
    "shortId": "abc123",
    "title": "신나는 춤",
    "type": "image/gif",
    "imageUrl": "https://cdn.jjalbot.com/2024/excited-dance.gif",
    "videoUrl": null,
    "thumbnailUrl": "https://cdn.jjalbot.com/2024/excited-dance-thumb.webp",
    "tags": ["신나는", "춤"],
    "views": 420,
    "nsfw": false,
    "metadata": {
      "contentType": "image/gif",
      "width": 480,
      "height": 360
    },
    "resources": [
      {
        "url": "https://cdn.jjalbot.com/2024/excited-dance-sm.webp",
        "contentType": "image/webp",
        "width": 240,
        "height": 180,
        "original": false
      }
    ],
    "createdAt": "2024-03-15T12:00:00.000Z"
  }
]

Random Jjals

GET /jjals/random?size=<n>&text=<keyword>

Get random jjal(s), optionally filtered by keyword.

Query Parameters

Parameter	Type	Required	Default	Description
`size`	number	No	1	Number of random jjals to return
`text`	string	No		Filter random results by keyword (must be Korean)

Example Request

# Get one random jjal
curl "https://api.jjalbot.com/jjals/random"

# Get 5 random jjals about cats
curl "https://api.jjalbot.com/jjals/random?text=고양이&size=5"

Example Response

[
  {
    "id": 9876,
    "shortId": "xyz789",
    "title": "놀란 고양이",
    "type": "image/jpeg",
    "imageUrl": "https://cdn.jjalbot.com/2024/surprised-cat.jpg",
    "videoUrl": null,
    "thumbnailUrl": null,
    "tags": ["고양이", "놀란"],
    "views": 150,
    "nsfw": false,
    "metadata": {
      "contentType": "image/jpeg",
      "width": 640,
      "height": 480
    },
    "resources": [],
    "createdAt": "2024-06-01T08:30:00.000Z"
  }
]

Get Jjal by ID

GET /jjals/:shortId

Fetch a single jjal by its short ID.

Path Parameters

Parameter	Type	Required	Description
`shortId`	string	Yes	The unique short ID of the jjal

Example Request

curl "https://api.jjalbot.com/jjals/abc123"

Example Response

{
  "id": 12345,
  "shortId": "abc123",
  "title": "신나는 춤",
  "type": "image/gif",
  "imageUrl": "https://cdn.jjalbot.com/2024/excited-dance.gif",
  "videoUrl": null,
  "thumbnailUrl": "https://cdn.jjalbot.com/2024/excited-dance-thumb.webp",
  "tags": ["신나는", "춤"],
  "views": 420,
  "nsfw": false,
  "metadata": {
    "contentType": "image/gif",
    "width": 480,
    "height": 360
  },
  "resources": [],
  "createdAt": "2024-03-15T12:00:00.000Z"
}

Returns null if no jjal is found with the given ID.

Response Object Schema

Each jjal object contains the following fields:

Field	Type	Description
`id`	number	Internal database ID
`shortId`	string	Unique short identifier (use this for URLs)
`title`	string	Title / description of the jjal
`type`	string	MIME type (e.g. `image/gif`, `image/jpeg`, `video/mp4`)
`imageUrl`	string	Direct URL to the image
`videoUrl`	string	Direct URL to the video (if applicable)
`thumbnailUrl`	string	Thumbnail image URL (may be null)
`tags`	string[]	Array of tag strings
`views`	number	View count
`nsfw`	boolean	Whether the content is NSFW
`metadata`	object	`{ contentType, width, height }`
`resources`	array	Encoded variants at different resolutions
`createdAt`	string	ISO 8601 creation timestamp

AI Agent / LLM Tool Use

If you are building an AI agent or LLM integration that needs to search for meme images, you can define the JjalBot search API as a tool.

OpenAI Function Calling Schema

{
  "type": "function",
  "function": {
    "name": "search_jjals",
    "description": "Search for Korean meme images (jjals) by keyword. Returns an array of jjal objects with image URLs. Keywords must be in Korean.",
    "parameters": {
      "type": "object",
      "properties": {
        "keyword": {
          "type": "string",
          "description": "The search keyword in Korean (e.g. '웃긴', '슬픈', '고양이')"
        }
      },
      "required": ["keyword"]
    }
  }
}

Implementation Example

import requests

def search_jjals(keyword: str) -> list:
    """Search for jjals by keyword."""
    response = requests.get(
        "https://api.jjalbot.com/jjals",
        params={"text": keyword}
    )
    return response.json()

# Example usage
results = search_jjals("신나는")
for jjal in results[:3]:
    print(f"{jjal['title']}: {jjal['imageUrl']}")

MCP (Model Context Protocol) Tool Definition

{
  "name": "search_jjals",
  "description": "Search for Korean meme images (jjals) by keyword from jjalbot.com. Keywords must be in Korean.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "keyword": {
        "type": "string",
        "description": "Search keyword in Korean (e.g. '웃긴', '슬픈', '고양이')"
      },
      "size": {
        "type": "number",
        "description": "Maximum number of results (for random endpoint)"
      }
    },
    "required": ["keyword"]
  }
}

CLI (Command Line)

You can search jjals directly from your terminal using npx:

# Search for jjals (keywords must be Korean)
npx jjalbot search "웃긴"

# Get random jjal(s)
npx jjalbot random
npx jjalbot random --size 5
npx jjalbot random --text "고양이"

# Get a specific jjal by ID
npx jjalbot get abc123

All commands output JSON to stdout, making them easy to pipe into other tools:

# Get the image URL of a random jjal
npx jjalbot random | jq '.[0].imageUrl'

# Search and download the first result
npx jjalbot search "엄지척" | jq -r '.[0].imageUrl' | xargs curl -O

Install globally for convenience:

npm install -g jjalbot
jjalbot search "대박"

Notes

Search keywords must be in Korean.
When exact text matching returns no results, the API automatically falls back to semantic (AI-powered vector similarity) search.
NSFW content is filtered out in production.
All image URLs are served from a CDN for fast delivery.
There are no authentication requirements for read endpoints.
Please be considerate with request volume.