imgpile

https://imgpile.com/developers
Admin
imgpile is an API platform for uploading, sharing, and managing images and videos with support for...
Tokens:11,756
Snippets:74
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Direct Image URL Examples

Source: https://imgpile.com/developers

Examples of direct CDN URLs for accessing uploaded media in various sizes.

```text
https://cdn.imgpile.com/f/{filename}.{ext}          — Original
https://cdn.imgpile.com/f/{filename}_xs.{ext}       — Extra small
https://cdn.imgpile.com/f/{filename}_sm.{ext}       — Small
https://cdn.imgpile.com/f/{filename}_md.{ext}       — Medium
https://cdn.imgpile.com/f/{filename}_lg.{ext}       — Large
https://cdn.imgpile.com/f/{filename}_xl.{ext}       — Extra large
https://cdn.imgpile.com/f/{filename}_thumb.jpg      — Thumbnail (videos)
```

--------------------------------

### Content Filtering Example

Source: https://imgpile.com/developers

This example shows how to request adult content using the '?nsfw=1' query parameter in a cURL request.

```bash
curl https://imgpile.com/api/v1/posts?nsfw=1
```

--------------------------------

### Upload Single File Response

Source: https://imgpile.com/developers

Example response after successfully uploading a single media file.

```json
{
  "message": "Media created successfully",
  "media": {
    "slug": "abc1234",
    "type": "image/jpeg",
    "urls": {
      "original": "https://cdn.imgpile.com/f/abc1234.jpg",
      "..." : "..."
    }
  }
}
```

--------------------------------

### Example Error Responses

Source: https://imgpile.com/developers

These are example JSON responses for common HTTP error codes.

```json
{ "message": "Unauthenticated." }
```

```json
{ "message": "This action is unauthorized." }
```

```json
{   "message": "The file field is required.",   "errors": {     "file": ["The file field is required."]   } }
```

```json
{ "message": "Too Many Attempts." }
```

```json
{ "error": "This file is not allowed." }
```

--------------------------------

### API Pagination Example

Source: https://imgpile.com/developers

This JSON structure shows the pagination metadata returned by list endpoints. Use the 'links.next' field to iterate through pages.

```json
{   "data": [ ... ],   "links": {     "first": "https://imgpile.com/api/v1/posts?page=1",     "last": "https://imgpile.com/api/v1/posts?page=42",     "prev": null,     "next": "https://imgpile.com/api/v1/posts?page=2"   },   "meta": {     "current_page": 1,     "from": 1,     "to": 10,     "per_page": 10,     "total": 421,     "last_page": 42   } }
```

--------------------------------

### Get Single Post

Source: https://imgpile.com/developers

Retrieves a single post by its slug, including paginated media.

```APIDOC
## GET /posts/{slug} Public

### Description
Get a single post with paginated media.

### Method
GET

### Endpoint
/posts/{slug}

### Path Parameters
- **slug** (string) - Required - The unique slug of the post.

### Query Parameters
- **mediaPage** (integer) - Optional - Page number for media (default 1)
- **perPage** (integer) - Optional - Media items per page (default 10)
- **key** (string) - Optional - Required for private posts. The owner can find this in the share link.

### Request Example
```bash
curl https://imgpile.com/api/v1/posts/MSGhYqy  # Private post with key: curl "https://imgpile.com/api/v1/posts/xyz789?key=ab12cd34ef"
```

### Response
#### Success Response (200)
- **data** (object) - The post object.
  - **id** (integer) - The unique identifier for the post.
  - **slug** (string) - The unique slug for the post.
  - **title** (string) - The title of the post.
  - **description** (string) - The description of the post.
  - **score** (integer) - The score of the post.
  - **view_count** (integer) - The number of views for the post.
  - **moderation_status** (string) - The moderation status of the post.
  - **user** (object) - Information about the post's author.
  - **media** (array) - An array of media items associated with the post.

#### Response Example
```json
{
  "data": {
    "id": 30713,
    "slug": "MSGhYqy",
    "title": "Sunset photos",
    "description": "...",
    "score": 12,
    "view_count": 245,
    "moderation_status": "approved",
    "user": { "username": "alice", ... },
    "media": [ ... ]
  }
}
```
```

--------------------------------

### Unauthenticated API Request

Source: https://imgpile.com/developers

Example of making a public GET request to the API without requiring authentication. Read endpoints do not need a bearer token.

```bash
curl https://imgpile.com/api/v1/posts
```

--------------------------------

### Get Single Media Item using cURL

Source: https://imgpile.com/developers

Fetch details for a specific media item using its unique slug.

```bash
curl https://imgpile.com/api/v1/media/abc1234
```

--------------------------------

### Get User Media

Source: https://imgpile.com/developers

Retrieve a list of media uploaded by a specific user. This endpoint is publicly accessible.

```bash
curl https://imgpile.com/api/v1/users/alice/media
```

--------------------------------

### Get Following Users

Source: https://imgpile.com/developers

Retrieve a paginated list of users that a specific user is following. This endpoint is publicly accessible.

```bash
curl https://imgpile.com/api/v1/users/alice/following
```

--------------------------------

### Example Error Responses

Source: https://imgpile.com/developers

Common error responses encountered when interacting with the API, including status codes and example JSON payloads.

```APIDOC
### Example error responses

**401 Unauthenticated**
```json
{ "message": "Unauthenticated." }
```
**403 Forbidden**
```json
{ "message": "This action is unauthorized." }
```
**422 Validation failed**
```json
{   "message": "The file field is required.",   "errors": {     "file": ["The file field is required."]   } }
```
**429 Rate limited**
```json
{ "message": "Too Many Attempts." }
```
Check the `Retry-After` response header for seconds until the limit resets.
**451 Banned content**
```json
{ "error": "This file is not allowed." }
```
```

--------------------------------

### Upload Image from Browser/Node.js

Source: https://imgpile.com/developers

Upload an image using JavaScript's Fetch API. This example demonstrates how to append a file to FormData and send it as a POST request to the media endpoint.

```javascript
const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('https://cdn.imgpile.com/api/v1/media', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
    },
    body: formData,
});

const { media } = await response.json();
console.log(media.urls.original); // https://cdn.imgpile.com/f/abc1234.jpg
```

--------------------------------

### GET /media - List Media Items

Source: https://imgpile.com/developers

Retrieve a list of media items with options for filtering, sorting, and pagination. This endpoint is public.

```APIDOC
## GET /media

### Description
List media items with filtering and pagination.

### Method
GET

### Endpoint
`https://imgpile.com/api/v1/media`

### Parameters
#### Query Parameters
- **tag** (string) - Optional - Filter by tag name.
- **sort** (string) - Optional - Sorting order. Accepts `latest` (default) or `random`.
- **period** (string) - Optional - Time period for filtering. Accepts `day`, `week`, `month`, `year`, `all`.
- **limit** (integer) - Optional - Results per page. Max 250, default 10.
- **username** (string) - Optional - Filter by username.
- **nsfw** (integer) - Optional - Set to `1` to include NSFW content. Default: SFW only.

### Request Example
```bash
curl https://imgpile.com/api/v1/media?limit=20
```

### Response
#### Success Response (200)
- **data** (array) - An array of media objects.
  - Each object contains:
    - **slug** (string) - Unique identifier for the media.
    - **type** (string) - MIME type of the media.
    - **width** (integer) - Width of the media in pixels.
    - **height** (integer) - Height of the media in pixels.
    - **moderation_status** (string) - Status of content moderation.
    - **urls** (object) - Object containing various URLs for the media.
- **links** (object) - Pagination links.
- **meta** (object) - Metadata about the pagination.
  - **current_page** (integer) - The current page number.
  - **total** (integer) - The total number of items.

#### Response Example
```json
{
  "data": [
    {
      "slug": "abc1234",
      "type": "image/jpeg",
      "width": 1920,
      "height": 1080,
      "moderation_status": "approved",
      "urls": {}
    }
  ],
  "links": {},
  "meta": {
    "current_page": 1,
    "total": 421
  }
}
```
```

--------------------------------

### Get User Followers

Source: https://imgpile.com/developers

Retrieve a paginated list of users who follow a specific user. This endpoint is publicly accessible.

```bash
curl https://imgpile.com/api/v1/users/alice/followers
```

--------------------------------

### GET /media/{slug} - Get Single Media Item

Source: https://imgpile.com/developers

Retrieve a single media item by its unique slug. This endpoint is public.

```APIDOC
## GET /media/{slug}

### Description
Get a single media item by its slug.

### Method
GET

### Endpoint
`https://imgpile.com/api/v1/media/{slug}`

### Parameters
#### Path Parameters
- **slug** (string) - Required - The unique identifier (slug) of the media item.

### Request Example
```bash
curl https://imgpile.com/api/v1/media/abc1234
```

### Response
#### Success Response (200)
- **data** (object) - The media item object.
  - **slug** (string) - Unique identifier for the media.
  - **type** (string) - MIME type of the media.
  - **width** (integer) - Width of the media in pixels.
  - **height** (integer) - Height of the media in pixels.
  - **moderation_status** (string) - Status of content moderation.
  - **urls** (object) - Object containing various URLs for the media.

#### Response Example
```json
{
  "data": {
    "slug": "abc1234",
    "type": "image/jpeg",
    "width": 1920,
    "height": 1080,
    "moderation_status": "approved",
    "urls": {}
  }
}
```
```

--------------------------------

### Get User Posts

Source: https://imgpile.com/developers

Retrieve a list of posts made by a specific user. This endpoint is publicly accessible.

```bash
curl https://imgpile.com/api/v1/users/alice/posts
```

--------------------------------

### Get User Comments

Source: https://imgpile.com/developers

Retrieve a paginated list of comments made by a specific user. This endpoint is publicly accessible.

```bash
curl https://imgpile.com/api/v1/users/alice/comments
```

--------------------------------

### Media Upload API

Source: https://imgpile.com/developers

Upload a single file (image or video) to get a direct CDN URL. This is ideal for hotlinking, embedding, or sharing.

```APIDOC
## POST /api/v1/media

### Description
Upload a single file and get a direct CDN URL. Perfect for ShareX, Discord bots, or any script that just needs to host an image.

### Method
POST

### Endpoint
`https://cdn.imgpile.com/api/v1/media`

### Parameters
#### Request Body
- **file** (file) - Required - The file to upload.

### Request Example
```bash
curl -X POST https://cdn.imgpile.com/api/v1/media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@photo.jpg"
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **media** (object) - Details about the uploaded media.
  - **slug** (string) - The unique identifier for the media.
  - **type** (string) - The MIME type of the media.
  - **urls** (object) - URLs for accessing the media.
    - **original** (string) - The direct CDN URL for the original media file.

#### Response Example
```json
{
  "message": "Media created successfully",
  "media": {
    "slug": "abc1234",
    "type": "image/jpeg",
    "urls": {
      "original": "https://cdn.imgpile.com/f/abc1234.jpg"
    }
  }
}
```
```

--------------------------------

### Create a New Post

Source: https://imgpile.com/developers

Requires authentication. Creates a new post by providing an array of media IDs. The response includes the new post's ID and slug.

```bash
curl -X POST https://imgpile.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_ids": [12345, 12346]}'
```

--------------------------------

### Upload Multiple Files and Create Post (curl)

Source: https://imgpile.com/developers

Upload multiple files individually and then create a post containing these media items. Media IDs are returned from the initial upload and used in the post creation request.

```bash
curl -X POST https://cdn.imgpile.com/api/v1/media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@photo1.jpg" # Returns: { "media": { "id": 12345, ... } }
```

```bash
curl -X POST https://imgpile.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_ids": [12345, 12346]}'
```

--------------------------------

### Create Post

Source: https://imgpile.com/developers

Creates a new post using provided media IDs. Requires authentication.

```APIDOC
## POST /posts Auth required

### Description
Create a new post from uploaded media.

### Method
POST

### Endpoint
/posts

### Request Body
- **media_ids** (array) - Required - Array of media IDs to include in the post

### Request Example
```bash
curl -X POST https://imgpile.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_ids": [12345, 12346]}'
```

### Response
#### Success Response (201)
- **message** (string) - Confirmation message.
- **post** (object) - Details of the created post.
  - **id** (integer) - The unique identifier for the post.
  - **slug** (string) - The unique slug for the post.

#### Response Example
```json
{
  "message": "Post created successfully",
  "post": {
    "id": 30720,
    "slug": "rtWJdHr"
  }
}
```
```

--------------------------------

### Upload Single File (curl)

Source: https://imgpile.com/developers

Upload a single file to cdn.imgpile.com and receive a direct CDN URL. This is suitable for scripts like ShareX or Discord bots that require image hosting.

```bash
curl -X POST https://cdn.imgpile.com/api/v1/media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@photo.jpg"
```

--------------------------------

### List Public Posts with Filtering

Source: https://imgpile.com/developers

Use this endpoint to list public posts. Supports filtering by tag, sorting, period, and pagination. Ensure the limit does not exceed 250.

```bash
curl https://imgpile.com/api/v1/posts?sort=latest
```

--------------------------------

### List Media Items using cURL

Source: https://imgpile.com/developers

Retrieve a list of media items with options for filtering and pagination. The default sort order is 'latest'.

```bash
curl https://imgpile.com/api/v1/media?limit=20
```

--------------------------------

### Retrieve a Single Post

Source: https://imgpile.com/developers

Fetches a single post and its paginated media. For private posts, an access key is required. Media pagination parameters are available.

```bash
curl https://imgpile.com/api/v1/posts/MSGhYqy
# Private post with key: curl "https://imgpile.com/api/v1/posts/xyz789?key=ab12cd34ef"
```

--------------------------------

### Update Media using cURL

Source: https://imgpile.com/developers

Modify the title or description of a media item you own. Requires authentication and sending JSON data.

```bash
curl -X PATCH https://imgpile.com/api/v1/media/abc1234 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New title"}'
```

--------------------------------

### Post Creation API

Source: https://imgpile.com/developers

Create a shareable post containing one or more media items. Posts can include a title, description, voting, and comments.

```APIDOC
## POST /api/v1/posts

### Description
Create a post with media IDs. This endpoint is used after uploading media files individually.

### Method
POST

### Endpoint
`https://imgpile.com/api/v1/posts`

### Parameters
#### Request Body
- **media_ids** (array of integers) - Required - An array of media IDs to include in the post.

### Request Example
```bash
curl -X POST https://imgpile.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_ids": [12345, 12346]}'
```

### Response
#### Success Response (201)
- **post** (object) - Details about the created post.
  - **slug** (string) - The unique identifier for the post.

#### Response Example
```json
{
  "post": {
    "slug": "xyz789"
  }
}
```
```

```APIDOC
## PATCH /api/v1/posts/{slug}

### Description
Update the title and description of an existing post.

### Method
PATCH

### Endpoint
`https://imgpile.com/api/v1/posts/{slug}`

### Parameters
#### Path Parameters
- **slug** (string) - Required - The slug of the post to update.

#### Request Body
- **title** (string) - Optional - The new title for the post.
- **description** (string) - Optional - The new description for the post.

### Request Example
```bash
curl -X PATCH https://imgpile.com/api/v1/posts/xyz789 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My post", "description": "Summer 2026"}'
```
```

--------------------------------

### POST /media - Upload Media

Source: https://imgpile.com/developers

Upload an image or video file to ImgPile. This endpoint requires authentication and should use multipart/form-data.

```APIDOC
## POST /media

### Description
Upload an image or video. Send as `multipart/form-data`.

### Method
POST

### Endpoint
`https://cdn.imgpile.com/api/v1/media`

### Parameters
#### Request Body
- **file** (file) - Required - The file to upload. Max 100 MB. Accepts image/* and video/*.
- **post_id** (string) - Optional - Attach to an existing post.

### Request Example
```bash
curl -X POST https://cdn.imgpile.com/api/v1/media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@photo.jpg"
```

### Response
#### Success Response (201)
- **message** (string) - Confirmation message.
- **media** (object) - Details of the uploaded media.
  - **slug** (string) - Unique identifier for the media.
  - **filename** (string) - The filename of the media.
  - **type** (string) - MIME type of the media.
  - **width** (integer) - Width of the media in pixels.
  - **height** (integer) - Height of the media in pixels.
  - **moderation_status** (string) - Status of content moderation.
  - **urls** (object) - Object containing various URLs for the media.
    - **original** (string) - URL to the original media file.

#### Response Example
```json
{
  "message": "Media created successfully",
  "media": {
    "slug": "abc1234",
    "filename": "abc1234",
    "type": "image/jpeg",
    "width": 1920,
    "height": 1080,
    "moderation_status": "approved",
    "urls": {
      "original": "https://cdn.imgpile.com/f/abc1234.jpg"
    }
  }
}
```
```

--------------------------------

### Follow a User

Source: https://imgpile.com/developers

Follow a specific user. Requires authentication. Calling this endpoint again will unfollow the user.

```bash
curl -X POST https://imgpile.com/api/v1/users/alice/follow \
   -H "Authorization: Bearer YOUR_TOKEN"
```

--------------------------------

### Update a Post

Source: https://imgpile.com/developers

Allows updating a post you own. Supports changing title, description, visibility, NSFW status, and media order. Setting visibility to 'private' auto-generates an access key.

```bash
curl -X PATCH https://imgpile.com/api/v1/posts/rtWJdHr \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated title", "visibility": "private"}'
```

--------------------------------

### Authentication

Source: https://imgpile.com/developers

Information on how to authenticate API requests.

```APIDOC
## Authentication

Read endpoints (GET) are public and do not require authentication. All other endpoints require a bearer token.

To authenticate, pass your token in the `Authorization` header:

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" https://cdn.imgpile.com/api/v1/media -F "file=@photo.jpg"
```

Generate an API token by logging in or registering on the imgpile website.
```

--------------------------------

### Authenticated API Request

Source: https://imgpile.com/developers

Demonstrates how to authenticate API requests by including the bearer token in the Authorization header. This is required for non-read endpoints.

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" https://cdn.imgpile.com/api/v1/media -F "file=@photo.jpg"
```

--------------------------------

### Direct Image URLs

Source: https://imgpile.com/developers

Information on accessing uploaded media directly via CDN URLs, with various size options available.

```APIDOC
### Description
Every uploaded file is served via the CDN. The media response includes a `urls` object with all available sizes.

### CDN URL Formats
- `https://cdn.imgpile.com/f/{filename}.{ext}` - Original
- `https://cdn.imgpile.com/f/{filename}_xs.{ext}` - Extra small
- `https://cdn.imgpile.com/f/{filename}_sm.{ext}` - Small
- `https://cdn.imgpile.com/f/{filename}_md.{ext}` - Medium
- `https://cdn.imgpile.com/f/{filename}_lg.{ext}` - Large
- `https://cdn.imgpile.com/f/{filename}_xl.{ext}` - Extra large
- `https://cdn.imgpile.com/f/{filename}_thumb.jpg` - Thumbnail (videos)
```

--------------------------------

### Update Post Metadata (curl)

Source: https://imgpile.com/developers

Optionally add a title and description to an existing post after its creation. Use the post's slug to target it for the update.

```bash
curl -X PATCH https://imgpile.com/api/v1/posts/xyz789 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My post", "description": "Summer 2026"}'
```

--------------------------------

### Delete Media using cURL

Source: https://imgpile.com/developers

Remove a media item you own from ImgPile. Requires authentication.

```bash
curl -X DELETE https://imgpile.com/api/v1/media/abc1234 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

--------------------------------

### Post Object

Source: https://imgpile.com/developers

Details of the Post object, representing a shareable container for one or more media items.

```APIDOC
## The Post object

A shareable container for one or more media items.

Field| Type| Description  
---|---|---
id| `integer`| Numeric ID. Use `slug` for URLs.
slug| `string`| Unique 7-character identifier. Used in URLs.
title| `string|null`| Post title.
description| `string|null`| Post description.
score| `integer`| Net vote score (upvotes minus downvotes).
view_count| `integer`| Total page views.
media_count| `integer`| Number of media items in this post.
moderation_status| `enum`| One of `approved`, `pending`, `nsfw`, or `rejected`. See Content Filtering.
isUpvotedByUser| `boolean`| Whether the authenticated user has upvoted this post.
isDownvotedByUser| `boolean`| Whether the authenticated user has downvoted this post.
created_at| `timestamp`| ISO 8601 timestamp.
user| `object|null`| The author (username, avatar). Null for guest posts.
media| `array`| Array of Media objects. Only included on single-post requests.
first_media| `object|null`| The first media (preview). Only included in feed responses.

Owner-only fields (returned to the post's owner only):
visibility| `enum`| `public`, `hidden`, or `private`.
access_key| `string|null`| Required to view a private post. Append as `?key=xxx`.
```

--------------------------------

### API Pagination

Source: https://imgpile.com/developers

List endpoints return paginated results. You can control the page size and navigate through pages using query parameters.

```APIDOC
## API Pagination

List endpoints (`GET /posts`, `GET /media`) return paginated results. The default page size is 10; you can request up to 250 with `?limit=N`.
Use `?page=N` to navigate pages. The response includes pagination metadata:
```json
{
  "data": [ ... ],
  "links": {
    "first": "https://imgpile.com/api/v1/posts?page=1",
    "last": "https://imgpile.com/api/v1/posts?page=42",
    "prev": null,
    "next": "https://imgpile.com/api/v1/posts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 10,
    "per_page": 10,
    "total": 421,
    "last_page": 42
  }
}
```
When iterating, follow `links.next` until it's `null`, or check `meta.current_page` against `meta.last_page`.
```

--------------------------------

### PATCH /media/{slug} - Update Media

Source: https://imgpile.com/developers

Update media details such as title and description for media that you own. This endpoint requires authentication.

```APIDOC
## PATCH /media/{slug}

### Description
Update media you own.

### Method
PATCH

### Endpoint
`https://imgpile.com/api/v1/media/{slug}`

### Parameters
#### Path Parameters
- **slug** (string) - Required - The unique identifier (slug) of the media item to update.

#### Request Body
- **title** (string) - Optional - The new title for the media.
- **description** (string) - Optional - The new description for the media.

### Request Example
```bash
curl -X PATCH https://imgpile.com/api/v1/media/abc1234 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New title"}'
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the media was updated.

#### Response Example
```json
{
  "message": "Media updated successfully"
}
```
```

--------------------------------

### List Public Posts

Source: https://imgpile.com/developers

Retrieves a list of public posts with options for filtering and pagination.

```APIDOC
## GET /posts Public

### Description
List public posts with filtering and pagination.

### Method
GET

### Endpoint
/posts

### Query Parameters
- **tag** (string) - Optional - Filter by tag name
- **sort** (string) - Optional - `latest` (default) or `random`
- **period** (string) - Optional - `day`, `week`, `month`, `year`, `all`
- **limit** (integer) - Optional - Results per page (max 250, default 10)
- **username** (string) - Optional - Filter by username
- **nsfw** (integer) - Optional - Set to `1` to include NSFW content. Default: SFW only.

### Request Example
```bash
curl https://imgpile.com/api/v1/posts?sort=latest
```

### Response
#### Success Response (200)
- **data** (array) - An array of post objects.
  - **id** (integer) - The unique identifier for the post.
  - **slug** (string) - The unique slug for the post.
  - **title** (string) - The title of the post.
  - **score** (integer) - The score of the post.
  - **view_count** (integer) - The number of views for the post.
  - **media_count** (integer) - The number of media items in the post.
  - **moderation_status** (string) - The moderation status of the post.
  - **user** (object) - Information about the post's author.
  - **first_media** (object) - Information about the first media item in the post.

#### Response Example
```json
{
  "data": [
    {
      "id": 30713,
      "slug": "MSGhYqy",
      "title": "Sunset photos",
      "score": 12,
      "view_count": 245,
      "media_count": 3,
      "moderation_status": "approved",
      "user": { "username": "alice", ... },
      "first_media": { ... }
    },
    ...
  ]
}
```
```

--------------------------------

### User Endpoints

Source: https://imgpile.com/developers

Endpoints for retrieving user-specific information such as posts, media, followers, and following status, as well as for managing follow relationships.

```APIDOC
## GET /users/{username}/posts

### Description
Get a user's posts.

### Method
GET

### Endpoint
/users/{username}/posts

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user.

### Response
#### Success Response (200)
- **data** (array) - An array of post objects, each containing details like id, slug, title, score, moderation_status, and first_media.

### Request Example
```bash
curl https://imgpile.com/api/v1/users/alice/posts
```

### Response Example
```json
{
  "data": [
    {
      "id": 30713,
      "slug": "MSGhYqy",
      "title": "Sunset photos",
      "score": 12,
      "moderation_status": "approved",
      "first_media": { ... }
    },
    ...
  ]
}
```
```

```APIDOC
## GET /users/{username}/media

### Description
Get a user's media.

### Method
GET

### Endpoint
/users/{username}/media

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user.

### Response
#### Success Response (200)
- **data** (array) - An array of media objects, each containing slug, type, moderation_status, and urls.

### Request Example
```bash
curl https://imgpile.com/api/v1/users/alice/media
```

### Response Example
```json
{
  "data": [
    {
      "slug": "abc1234",
      "type": "image/jpeg",
      "moderation_status": "approved",
      "urls": { ... }
    },
    ...
  ]
}
```
```

```APIDOC
## GET /users/{username}/comments

### Description
Get a user's comments (paginated).

### Method
GET

### Endpoint
/users/{username}/comments

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user.
```

```APIDOC
## GET /users/{username}/followers

### Description
Get a user's followers (paginated).

### Method
GET

### Endpoint
/users/{username}/followers

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user.
```

```APIDOC
## GET /users/{username}/following

### Description
Get the users this user is following (paginated).

### Method
GET

### Endpoint
/users/{username}/following

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user.
```

```APIDOC
## POST /users/{username}/follow

### Description
Follow a user.

### Method
POST

### Endpoint
/users/{username}/follow

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user to follow.

### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

### Request Example
```bash
curl -X POST https://imgpile.com/api/v1/users/alice/follow \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response Example
```json
{
  "message": "User followed."
}
```
```

```APIDOC
## DELETE /users/{username}/follow

### Description
Unfollow a user.

### Method
DELETE

### Endpoint
/users/{username}/follow

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user to unfollow.

### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

### Request Example
```bash
curl -X DELETE https://imgpile.com/api/v1/users/alice/follow \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response Example
```json
{
  "message": "User unfollowed."
}
```
```

--------------------------------

### Rate Limits

Source: https://imgpile.com/developers

Information on API rate limits for public and authenticated requests, file uploads, and file size/type restrictions.

```APIDOC
## Rate Limits

* **Public requests** (no token): 30 requests/minute per IP
* **Authenticated requests** : 120 requests/minute per user
* **File uploads** : 1,000 files/day per user/IP
* **Max file size** : 100 MB
* **Accepted types** : image/* and video/*

Rate limit headers are included in every response (`X-RateLimit-Limit`, `X-RateLimit-Remaining`).
```

--------------------------------

### Media Object

Source: https://imgpile.com/developers

Details of the Media object, which is returned by media endpoints and embedded within post responses.

```APIDOC
## The Media object

Returned by media endpoints and embedded inside post responses.

Field| Type| Description  
---|---|---
slug| `string`| Unique 7-character identifier. Used in URLs.
filename| `string`| Storage filename (same as slug).
title| `string|null`| User-provided title.
description| `string|null`| User-provided description.
type| `string`| MIME type — e.g. `image/jpeg`, `video/mp4`.
width| `integer`| Pixel width.
height| `integer`| Pixel height.
moderation_status| `enum`| One of `approved`, `pending`, `nsfw`, or `rejected`. See Content Filtering.
processed| `boolean`| `false` while sized variants are being generated; `true` when ready.
created_at| `timestamp`| ISO 8601 timestamp.
urls| `object`| CDN URLs at every available size — see Direct Image URLs.
user| `object|null`| The uploader (username, avatar). Null for guest uploads.
```

--------------------------------

### Add a Comment to a Post

Source: https://imgpile.com/developers

Requires authentication. Adds a comment to a specified post. Supports threaded replies by providing a parent comment ID. Content is limited to 500 characters.

```bash
curl -X POST https://imgpile.com/api/v1/posts/MSGhYqy/comments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Nice shot!"}'
```

--------------------------------

### DELETE /media/{slug} - Delete Media

Source: https://imgpile.com/developers

Delete media that you own. This endpoint requires authentication.

```APIDOC
## DELETE /media/{slug}

### Description
Delete media you own.

### Method
DELETE

### Endpoint
`https://imgpile.com/api/v1/media/{slug}`

### Parameters
#### Path Parameters
- **slug** (string) - Required - The unique identifier (slug) of the media item to delete.

### Request Example
```bash
curl -X DELETE https://imgpile.com/api/v1/media/abc1234 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the media was deleted.

#### Response Example
```json
{
  "message": "Media deleted successfully."
}
```
```

--------------------------------

### Error Handling

Source: https://imgpile.com/developers

Details on API error responses and status codes.

```APIDOC
## Errors

The API returns standard HTTP status codes. Error responses include a JSON body with a `message` (or `error`) field describing what went wrong.

### Status Codes

| Code | Meaning |
|---|---|
| `200` | OK — request succeeded |
| `201` | Created — resource was created |
| `400` | Bad Request — malformed request |
| `401` | Unauthenticated — missing or invalid token |
| `403` | Forbidden — you don't have permission for this action |
| `404` | Not Found — resource doesn't exist |
| `422` | Validation failed — request body has invalid fields |
| `429` | Rate Limited — too many requests, slow down |
| `451` | Unavailable for Legal Reasons — file matched a banned hash |
| `500` | Server Error — something went wrong on our end |
```

--------------------------------

### Content Filtering

Source: https://imgpile.com/developers

Control the content returned by list endpoints by specifying moderation status. By default, only 'approved' content is returned.

```APIDOC
## Content Filtering

By default, list endpoints (`GET /posts`, `GET /media`) only return safe content (moderation status `approved`). To also include adult content (`nsfw`), pass `?nsfw=1`:
```bash
curl https://imgpile.com/api/v1/posts?nsfw=1
```
Banned content (`rejected`, i.e. spam or abuse) is never returned to public feed endpoints regardless of the `?nsfw` flag.

Every post and media response includes a `moderation_status` field so you can warn, blur, or hide flagged items in your client:
```json
{
  "moderation_status": "approved" | "pending" | "nsfw" | "rejected",
  ...
}
```
* `approved` — safe for all audiences.
* `pending` — awaiting automated moderation.
* `nsfw` — adult content; only returned from public endpoints when `?nsfw=1`.
* `rejected` — spam/abuse; never returned to public endpoints.

Hidden posts are accessible by their slug but never appear in feeds. Private posts require an `?key=xxx` query parameter (the owner can find this in the post's share link).
```

--------------------------------

### Add Comment to Post

Source: https://imgpile.com/developers

Adds a comment to a specific post. Requires authentication.

```APIDOC
## POST /posts/{post}/comments Auth required

### Description
Add a comment to a post.

### Method
POST

### Endpoint
/posts/{post}/comments

### Path Parameters
- **post** (string) - Required - The slug or ID of the post to comment on.

### Request Body
- **content** (string) - Required - Comment text (max 500 characters)
- **parent_id** (integer) - Optional - Comment ID to reply to (for threaded replies)

### Request Example
```bash
curl -X POST https://imgpile.com/api/v1/posts/MSGhYqy/comments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Nice shot!"}'
```

### Response
#### Success Response (201)
- **success** (boolean) - Indicates if the operation was successful.
- **comment** (object) - The created comment object.
  - **id** (integer) - The unique identifier for the comment.
  - **content** (string) - The text of the comment.
  - **user_id** (integer) - The ID of the user who posted the comment.
  - **post_id** (integer) - The ID of the post the comment belongs to.

#### Response Example
```json
{
  "success": true,
  "comment": {
    "id": 456,
    "content": "Nice shot!",
    "user_id": 1,
    "post_id": 12345
  }
}
```
```

--------------------------------

### Update Post

Source: https://imgpile.com/developers

Updates an existing post owned by the authenticated user. Requires authentication.

```APIDOC
## PATCH /posts/{slug} Auth required

### Description
Update a post you own.

### Method
PATCH

### Endpoint
/posts/{slug}

### Path Parameters
- **slug** (string) - Required - The unique slug of the post to update.

### Request Body
- **title** (string) - Optional - Post title (max 255)
- **description** (string) - Optional - Post description
- **visibility** (string) - Optional - `public`, `hidden`, or `private`. Setting to `private` auto-generates an `access_key`.
- **is_nsfw** (boolean) - Optional - Mark the post as adult content.
- **media_order** (array) - Optional - Array of media slugs in desired order

### Request Example
```bash
curl -X PATCH https://imgpile.com/api/v1/posts/rtWJdHr \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated title", "visibility": "private"}'
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **visibility** (string) - The updated visibility status of the post.
- **access_key** (string) - The access key generated if visibility was set to `private`.

#### Response Example
```json
{
  "message": "Post updated successfully",
  "visibility": "private",
  "access_key": "ab12cd34ef"
}
```
```

--------------------------------

### Delete a Post

Source: https://imgpile.com/developers

Requires authentication. Deletes a post that you own. A confirmation message is returned upon successful deletion.

```bash
curl -X DELETE https://imgpile.com/api/v1/posts/rtWJdHr \
  -H "Authorization: Bearer YOUR_TOKEN"
```

--------------------------------

### Upvote a Post

Source: https://imgpile.com/developers

Upvote a specific post. Requires authentication. Calling this endpoint again will remove the upvote.

```bash
curl -X POST https://imgpile.com/api/v1/posts/123/upvote \
   -H "Authorization: Bearer YOUR_TOKEN"
```
Tokens:
Raw