Developer Reference
Public REST API v1 for accessing albums and files data programmatically. All responses are JSON. Authentication is required for all endpoints.
curl -H "Authorization: Bearer YOUR_KEY" \
"https://api.bunkrr.pics/v1/albums?limit=5"All API requests require an API key. Include it in every request using one of these methods:
Authorization: Bearer YOUR_API_KEYX-API-Key: YOUR_API_KEYContact the administrator to obtain an API key. Keys are unique per developer and can be revoked at any time.
https://api.bunkrr.pics/v1Default rate limit is 1000 requests per minute per API key. Rate limit headers are included in every response:
| Header | Description |
|---|---|
| X-RateLimit-Limit | Max requests per window |
| X-RateLimit-Remaining | Remaining requests in current window |
| Retry-After | Seconds to wait (only on 429) |
All list endpoints use cursor-based pagination. Responses include a pagination object:
{
"data": [...],
"pagination": {
"next_cursor": "eyJpZCI6MTIzfQ",
"has_more": true,
"limit": 50
}
}Pass the next_cursor value as the cursor query parameter to fetch the next page. Default limit is 50, maximum is 100.
A cursor is tied to the sort it was issued with. Keep sort(and any filters) unchanged across pages of the same listing — do not pass a cursor obtained under one sort to a request with a different one. Treat the cursor as opaque; its format may change while the v1 API is in beta, so always start pagination without a cursor and follow next_cursor.
List all albums with cursor pagination.
| Name | Type | Description |
|---|---|---|
| cursor | string | Pagination cursor from previous response |
| limit | integer | Items per page (1-100, default 50) |
| sort | string | Sort order: date_desc (default), date_asc, size_desc, size_asc, name_asc, name_desc |
curl -H "Authorization: Bearer YOUR_KEY" \
"https://api.bunkrr.pics/v1/albums?limit=10"{
"data": [
{
"id": 1234,
"name": "Album Name",
"url": "https://bunkr.../a/...",
"file_count": 42,
"total_size_bytes": 1073741824,
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-03-20T14:00:00Z"
}
],
"pagination": {
"next_cursor": "eyJpZCI6MTIzMH0",
"has_more": true,
"limit": 10
}
}Get a single album by ID.
| Name | Type | Description |
|---|---|---|
| idrequired | integer | Album ID (path parameter) |
curl -H "Authorization: Bearer YOUR_KEY" \
"https://api.bunkrr.pics/v1/albums/1234"{
"data": {
"id": 1234,
"name": "Album Name",
"url": "https://bunkr.../a/...",
"file_count": 42,
"total_size_bytes": 1073741824,
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-03-20T14:00:00Z"
}
}List files in a specific album.
| Name | Type | Description |
|---|---|---|
| idrequired | integer | Album ID (path parameter) |
| cursor | string | Pagination cursor |
| limit | integer | Items per page (1-100, default 50) |
| ext | string | Filter by extension (e.g., mp4, jpg, or comma-separated: mp4,mkv) |
| min_size_bytes | integer | Minimum file size in bytes |
| max_size_bytes | integer | Maximum file size in bytes |
curl -H "Authorization: Bearer YOUR_KEY" \
"https://api.bunkrr.pics/v1/albums/1234/files?ext=mp4&limit=20"{
"data": [
{
"id": 5678,
"album_id": 1234,
"album_name": null,
"filename": "video.mp4",
"extension": "mp4",
"size_bytes": 52428800,
"size_human": "50.00 MB",
"source_url": "https://...",
"thumbnail_url": "https://...",
"created_at": "2025-01-15T10:30:00Z"
}
],
"pagination": {
"next_cursor": "eyJpZCI6NTY3MH0",
"has_more": true,
"limit": 20
}
}List all files globally with filters.
| Name | Type | Description |
|---|---|---|
| cursor | string | Pagination cursor |
| limit | integer | Items per page (1-100, default 50) |
| sort | string | Sort order: date_desc (default), date_asc, size_desc, size_asc |
| ext | string | Filter by extension (comma-separated) |
| min_size_bytes | integer | Minimum file size in bytes |
| max_size_bytes | integer | Maximum file size in bytes |
| album_id | integer | Filter by album ID |
curl -H "Authorization: Bearer YOUR_KEY" \
"https://api.bunkrr.pics/v1/files?ext=jpg,png&min_size_bytes=1048576&sort=size_desc"{
"data": [
{
"id": 5678,
"album_id": 1234,
"album_name": "Album Name",
"filename": "photo.jpg",
"extension": "jpg",
"size_bytes": 5242880,
"size_human": "5.00 MB",
"source_url": "https://...",
"thumbnail_url": "https://...",
"created_at": "2025-01-15T10:30:00Z"
}
],
"pagination": {
"next_cursor": "eyJpZCI6NTY3MH0",
"has_more": true,
"limit": 50
}
}Get a single file by ID.
| Name | Type | Description |
|---|---|---|
| idrequired | integer | File ID (path parameter) |
curl -H "Authorization: Bearer YOUR_KEY" \
"https://api.bunkrr.pics/v1/files/5678"{
"data": {
"id": 5678,
"album_id": 1234,
"album_name": "Album Name",
"filename": "photo.jpg",
"extension": "jpg",
"size_bytes": 5242880,
"size_human": "5.00 MB",
"source_url": "https://...",
"thumbnail_url": "https://...",
"created_at": "2025-01-15T10:30:00Z"
}
}Full-text search across files.
| Name | Type | Description |
|---|---|---|
| qrequired | string | Search query |
| cursor | string | Pagination cursor |
| limit | integer | Items per page (1-100, default 50) |
| sort | string | Sort: relevance (default), date_desc, date_asc, size_desc, size_asc |
| ext | string | Filter by extension (comma-separated) |
| min_size_bytes | integer | Minimum file size in bytes |
| max_size_bytes | integer | Maximum file size in bytes |
curl -H "Authorization: Bearer YOUR_KEY" \
"https://api.bunkrr.pics/v1/search?q=nature&ext=mp4&limit=10"{
"data": [...],
"total": 1542,
"pagination": {
"next_cursor": "eyJpZCI6MCwic29ydF92YWwiOjJ9",
"has_more": true,
"limit": 10
}
}All errors return a JSON object with an error field:
| Status | Meaning |
|---|---|
| 400 | Bad request (invalid parameters) |
| 401 | Missing or invalid API key |
| 403 | API key revoked |
| 404 | Resource not found |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
| 503 | Search service unavailable |
{
"error": "Invalid API key."
}