API Documentation

REST API for programmatic image management

v1.0RESTJSON

Authentication

All API requests require an API key. Include it in the x-api-key request header. API keys can be generated from your dashboard. API access requires a Pro or Business plan.

Rate Limits: 60 requests per minute per API key. Exceeding this returns a 429 status.

bash

curl -X GET https://imghoster.com/api/v1/images \
  -H "x-api-key: ihk_YOUR_API_KEY_HERE"

Upload Image

Upload an image file. Returns the image URL and embed codes.

POST/api/v1/upload

Request (multipart/form-data)

Field	Type	Required	Description
file	File	Yes	Image file to upload

Example

bash

curl -X POST https://imghoster.com/api/v1/upload \
  -H "x-api-key: ihk_YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg"

Response

json

{
  "success": true,
  "data": {
    "id": "clxyz123abc",
    "url": "https://imghoster.com/uploads/uuid.jpg",
    "directUrl": "https://imghoster.com/uploads/uuid.jpg",
    "htmlEmbed": "<img src=\"https://imghoster.com/uploads/uuid.jpg\" alt=\"image.jpg\" />",
    "markdownEmbed": "![image.jpg](https://imghoster.com/uploads/uuid.jpg)",
    "bbcodeEmbed": "[img]https://imghoster.com/uploads/uuid.jpg[/img]",
    "size": 204800,
    "filename": "uuid.jpg",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

List Images

Retrieve a paginated list of your uploaded images.

GET/api/v1/images

Query Parameters

Param	Default	Description
page	1	Page number
limit	20	Results per page (max 100)

bash

curl -X GET "https://imghoster.com/api/v1/images?page=1&limit=10" \
  -H "x-api-key: ihk_YOUR_API_KEY"

Delete Image

Permanently delete an image by its ID.

DELETE/api/v1/images

bash

curl -X DELETE https://imghoster.com/api/v1/images \
  -H "x-api-key: ihk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "clxyz123abc"}'

json

{
  "success": true,
  "message": "Image deleted"
}

Error Codes

Standard HTTP status codes are used throughout the API.

Status	Meaning
`200`	OK – Request successful
`201`	Created – Resource created
`400`	Bad Request – Invalid parameters
`401`	Unauthorized – Invalid or missing API key
`403`	Forbidden – Account banned or insufficient plan
`404`	Not Found – Resource not found
`429`	Too Many Requests – Rate limit exceeded
`500`	Internal Server Error – Contact support