Developers
API reference
Complete reference for the Mungfali Image Search REST API — authentication, endpoints, parameters, responses, limits, and errors.
Mungfali exposes a single read-only search endpoint over HTTPS. Every successful call returns JSON with your query in name and an array of image objects in value. Create API keys in the dashboard after signing up.
Base URL
Send all requests to:
https://mungfali.net
The canonical search path is /v1/search. The same handler is also available at /api/v1/images/search for backward compatibility.
Authentication
API keys use the mgf_live_ prefix. Include your key on every request — keys are scoped to your organization and can be rotated from Dashboard → API Keys.
Security: Store keys in environment variables. Never embed them in mobile apps or front-end JavaScript; proxy requests through your server instead.
X-API-Key header (recommended)
curl -s "https://mungfali.net/v1/search?q=mountains&count=20" \ -H "X-API-Key: mgf_live_your_key_here"
Authorization Bearer
curl -s "https://mungfali.net/v1/search?q=mountains&count=20" \ -H "Authorization: Bearer mgf_live_your_key_here"
Search images
GET/v1/search
Search for images by keyword. Only GET is supported; there is no request body.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | Required | Search query (keywords, phrases). Required on every request. URL-encode spaces and special characters. |
count | integer | Optional | Number of images to return. Range 1–150. Default is determined by the upstream provider when omitted. |
safesearch | string | Optional | Adult-content filter passed to the image provider. Typical values: strict, moderate, off. Omit to use provider defaults. |
transparent | string | Optional | When set (e.g. true or 1), filters out images with transparent backgrounds (PNG alpha). Useful for uniform thumbnails and grids. |
site | string | Optional | Restrict results to a single domain (e.g. unsplash.com or pexels.com). |
color | string | Optional | Bias results toward images with a dominant color (provider-specific; hex without #, e.g. C21C09). |
Example request
curl -s "https://mungfali.net/v1/search?q=cats&count=50&safesearch=moderate" \ -H "X-API-Key: mgf_live_your_key_here"
Response format
200 OK — JSON object with name (echo of your query) and value (array of 0–150 image objects).
{
"name": "car",
"value": [
{
"name": "Luxury Car Photos, Download The BEST Free Luxury Car Stock Photos & HD ...",
"FamilyFriendly": true,
"imageUrl": "https://images.pexels.com/photos/3729464/pexels-photo-3729464.jpeg?cs=srgb&dl=pexels-mikebirdy-3729464.jpg&fm=jpg",
"hostUrl": "https://www.pexels.com/search/luxury%20car/",
"contentSize": "1781235 B",
"width": 5456,
"height": 3632,
"isTransparent": false,
"accentColor": "C21C09"
},
{
"name": "New Car HD Wallpapers - Wallpaper Cave",
"FamilyFriendly": true,
"imageUrl": "https://wallpapercave.com/wp/wp2775459.jpg",
"hostUrl": "https://wallpapercave.com/new-car-hd-wallpaper",
"contentSize": "215010 B",
"width": 1440,
"height": 900,
"isTransparent": false,
"accentColor": "B9AA12"
}
]
}Response fields
| Field | Scope | Description |
|---|---|---|
name | root | The search query string echoed in the response. |
value | root | Array of image result objects (up to your requested count, max 150). |
name | item | Title or description of the image. |
FamilyFriendly | item | Whether the image passed SafeSearch filtering. |
imageUrl | item | Direct URL of the image file. |
hostUrl | item | URL of the page where the image was found. |
contentSize | item | Approximate file size of the image. |
width | item | Image width in pixels. |
height | item | Image height in pixels. |
isTransparent | item | True if the image has a transparent background (PNG). |
accentColor | item | Dominant accent color as a hex string (without #). |
Response headers
Successful responses include quota and rate-limit headers so you can monitor usage without an extra API call:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum API requests allowed per minute for your plan. |
X-RateLimit-Remaining | Requests remaining in the current one-minute window. |
X-RateLimit-Reset | ISO 8601 timestamp when the per-minute rate limit window resets (only on 429 rate-limit responses). |
X-Monthly-Quota-Limit | Total searches included in your plan for the current billing month. |
X-Monthly-Quota-Remaining | Searches remaining before monthly quota is exhausted. |
Rate limits and quota
Each plan includes a monthly search quota and a per-minute rate limit. One successful search consumes one unit of monthly quota. When quota is exhausted, the API returns 429 with {"error":"Monthly quota exceeded"}. When the per-minute limit is hit, you receive 429 with rate-limit headers and {"error":"Rate limit exceeded"}.
| Plan | Monthly searches | Rate limit |
|---|---|---|
| Free | 250 | 10 / min |
| Starter | 10,000 | 60 / min |
| Growth | 50,000 | 300 / min |
| Pro | 150,000 | 1,000 / min |
| Business | 1,000,000 | 5,000 / min |
See pricing for current plan pricing. Upgrade anytime from Dashboard → Billing.
Error responses
Errors return JSON with an error string and an appropriate HTTP status code:
{
"error": "Invalid API key"
}| Code | Status | Description |
|---|---|---|
| 200 | OK | Request succeeded. JSON body contains name and value array. |
| 400 | Bad Request | Missing or empty q parameter, or malformed query string. |
| 401 | Unauthorized | API key missing, invalid, or revoked. Send X-API-Key or Authorization: Bearer. |
| 402 | Payment Required | Organization has no active subscription. Upgrade or renew in the dashboard. |
| 429 | Too Many Requests | Monthly search quota exhausted, or per-minute rate limit exceeded. |
| 500 | Internal Server Error | Upstream provider error or unexpected failure. Retry with exponential backoff. |
Next steps
- Examples — integration patterns and copy-paste code
- SDKs — thin client wrappers for Node.js and Python
- Dashboard docs — interactive reference with copy buttons (requires login)
- Status — platform availability