API Documentation

The OnlyPepes public API lets you fetch, search, and paginate through the full collection of pepe images. All endpoints return JSON.

GET /api/pepe

List, search, or randomly browse pepe images with pagination.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	`1`	Results per page. Min `1`, max `25`.
`page`	integer	`1`	Page number (1-indexed).
`search`	string	—	Search query. Matches against tags and description via full-text search.
`field`	string	`text`	`text` for full-text search, `id` to look up by UUID.
`sort`	string	`created_at_desc`	`created_at_desc` or `created_at_asc`. Ignored when `random=true`.
`random`	boolean	`false`	Return results in random order.

Behavior

When limit=1 the response data is a single object (not an array). If a search has no matches it falls back to a random pepe and meta.search.found will be false.
When limit>1 the response data is an array with full pagination metadata.

Response — Paginated (limit > 1)

GET https://onlypepes.com/api/pepe?limit=3&page=1&random=true

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "file_name": "550e8400-e29b-41d4-a716-446655440000.png",
      "file_ext": ".png",
      "file_size": 284012,
      "tags": [
        "smug",
        "classic"
      ],
      "description": "Classic smug Pepe with a subtle grin",
      "url": "https://onlypepes.com/images/550e8400-e29b-41d4-a716-446655440000.png",
      "phash": "a4c3b2d1e5f6...",
      "created_at": "2025-06-15T10:30:00.000Z",
      "updated_at": "2025-06-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 3,
      "total_items": 1842,
      "total_pages": 615,
      "has_next": true,
      "has_previous": false
    },
    "search": {
      "terms": "",
      "found": true
    },
    "sort": "created_at_desc"
  },
  "error": null
}

Response — Single (limit = 1)

GET https://onlypepes.com/api/pepe?search=smug

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "file_name": "550e8400-e29b-41d4-a716-446655440000.png",
    "file_ext": ".png",
    "file_size": 284012,
    "tags": [
      "smug",
      "classic"
    ],
    "description": "Classic smug Pepe with a subtle grin",
    "url": "https://onlypepes.com/images/550e8400-e29b-41d4-a716-446655440000.png",
    "phash": "a4c3b2d1e5f6...",
    "created_at": "2025-06-15T10:30:00.000Z",
    "updated_at": "2025-06-15T10:30:00.000Z"
  },
  "meta": {
    "search": {
      "terms": "smug",
      "found": true
    }
  },
  "error": null
}

Aliases

Equivalent paths: /api/pepe, /api/pepe_image, /api/public/pepe, /api/public/pepes.

GET /api/pepe/:id

Fetch a single pepe by its UUID.

Path Parameters

Parameter	Type	Description
`id`	UUID	The unique identifier of the pepe image.

Response — Success

GET https://onlypepes.com/api/pepe/550e8400-e29b-41d4-a716-446655440000

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "file_name": "550e8400-e29b-41d4-a716-446655440000.png",
    "file_ext": ".png",
    "file_size": 284012,
    "tags": [
      "smug",
      "classic"
    ],
    "description": "Classic smug Pepe with a subtle grin",
    "url": "https://onlypepes.com/images/550e8400-e29b-41d4-a716-446655440000.png",
    "phash": "a4c3b2d1e5f6...",
    "created_at": "2025-06-15T10:30:00.000Z",
    "updated_at": "2025-06-15T10:30:00.000Z"
  },
  "error": null
}

Response — Not Found

{
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Pepe image not found: 550e8400-e29b-41d4-a716-446655440000"
  }
}

GET /images/:file_name

Serves the actual image file. The URL matches the url field returned by the API. Responses are served directly by nginx with 30-day immutable caching headers.

Error Responses

All errors follow the same shape. HTTP status codes used: 400 validation, 404 not found, 500 server error.

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR | NOT_FOUND | INTERNAL_SERVER_ERROR",
    "message": "Human-readable description"
  }
}

Pepe Object Fields

Field	Type	Description
`id`	string (UUID)	Unique identifier.
`file_name`	string	File name including extension.
`file_ext`	string	File extension (e.g. `.png`).
`file_size`	number	File size in bytes.
`tags`	string[] \| null	Array of tags, or null if untagged.
`description`	string \| null	Human-readable description.
`url`	string	Full public URL to the image.
`phash`	string	Perceptual hash for duplicate detection.
`created_at`	string (ISO 8601)	When the image was added.
`updated_at`	string (ISO 8601)	When the record was last modified.