API Reference

Documentation

Everything you need to use Mockly — built-in resources, user templates, query parameters, and middleware.

Overview

No Setup

100+ endpoints ready instantly — no account, no config.

CORS Enabled

Works directly from browsers and frontend apps.

Realistic Data

Powered by 50+ data generators for authentic-looking data.

Free Forever

No rate limits, no plans, no credit card required.

Base URL: https://api.mockly.codes
All endpoints listed in this reference are relative to this base.

Quick Start

No account needed. Copy, paste, run.

# Get 10 products
curl "https://api.mockly.codes/products?limit=10"

# Search users
curl "https://api.mockly.codes/users?q=john&limit=5"

# Sort products by price (descending)
curl "https://api.mockly.codes/products?sort=price&order=desc"

# Filter by field + paginate
curl "https://api.mockly.codes/products?category=Electronics&limit=20&page=2"

# Select specific fields only
curl "https://api.mockly.codes/products?fields=id,name,price&limit=50"

Endpoints

PatternDescription
GET /{resource}Paginated list of items — supports all query parameters
GET /{resource}/{id}Single item by numeric ID (1–100)
GET /{resource}/metaJSON Schema definition for the resource
GET /t/{templateId}User template endpoint — requires API key header
GET /v1/{slug}Featured template shorthand (same as /{resource})
GET /API info: version, available resources, categories

Replace {resource} with any resource slug, e.g. products, users, orders. See the full resource list below.

Authentication

Built-in ResourcesNo auth

All 100+ built-in resources are completely public. No header required.

curl "https://api.mockly.codes/products"
User TemplatesAPI key

Custom templates require an API key in the Authorization header.

curl -H "Authorization: Bearer mk_your_key" \
  "https://api.mockly.codes/t/{templateId}"
Get an API key at mockly.codes/dashboard/api-keys after signing in. Keys starting with mk_ are personal; mak_ keys work for public templates.

Query Parameters

ParameterTypeDefaultDescription
limitint 1–10010Number of items to return per page
pageint1Page number (1-based)
offsetintManual offset; overrides page if set
sortstringField name to sort results by
orderstringascSort direction: asc or desc
qstringFull-text search query across all fields
search_fieldsstringComma-separated fields to restrict search to
fieldsstringComma-separated fields to include in response
{field}=valuestringFilter by exact or operator-qualified value
delayint (ms)Simulate network latency (max 30,000 ms)
flakyRatefloat 0–1Probability of returning a 503 error
skip_cacheboolfalseBypass the response cache for fresh data
localestringBCP-47 locale tag — generates locale-aware names, cities, phones (e.g. en-IN, ja-JP, de-DE)
# Combine multiple parameters
curl "https://api.mockly.codes/products?\
  q=laptop&search_fields=name,description&\
  sort=price&order=asc&\
  page=1&limit=20&\
  fields=id,name,price,rating"

Filtering

Filter results by appending operators to field names: ?{field}{operator}={value}

OperatorMeaningExample
=Equals (default)?category=Electronics
!=Not equals?status!=inactive
>Greater than?price>100
>=Greater than or equal?rating>=4
<Less than?price<500
<=Less than or equal?stock<=10
~containsContains substring?name~contains=pro
~startsWithStarts with?slug~startsWith=us
~endsWithEnds with?email~endsWith=.com
# Price range + in-stock filter
curl "https://api.mockly.codes/products?price>=100&price<=500&in_stock=true"

# Name contains + sorted
curl "https://api.mockly.codes/products?name~contains=pro&sort=price&order=asc"

Middleware & Headers

Mockly includes built-in middleware for testing resilience, multi-tenancy, and access control.

Delay Simulation?delay=ms

Simulate slow network responses. Max 30,000 ms.

curl "https://api.mockly.codes/products?delay=2000"   # 2 second delay
Chaos Engineering?flakyRate=0.0–1.0

Randomly returns 503 errors at the given probability. Test your retry logic.

curl "https://api.mockly.codes/products?flakyRate=0.3"  # 30% chance of failure
Locale-Aware Data?locale=BCP-47

Generate locale-specific names, cities, phone numbers, and postal codes. Bypasses cache automatically. Supported: en-IN, ja-JP, de-DE, fr-FR, zh-CN, pt-BR, es-ES, ko-KR, ar-SA, en-GB.

curl "https://api.mockly.codes/users?locale=en-IN&limit=5"   # Indian users
curl "https://api.mockly.codes/employees?locale=ja-JP&limit=10" # Japanese employees
Request Headers
HeaderDescription
X-Tenant-IDIsolate data by tenant — same tenant always gets same data
X-RoleSimulate RBAC: admin, user, guest, or any custom role
Idempotency-KeyMake POST/PUT/PATCH idempotent — response cached 24h
X-Request-IDCustom trace ID echoed back in response headers
# Multi-tenant + role simulation
curl -H "X-Tenant-ID: tenant-a" -H "X-Role: admin" \
  "https://api.mockly.codes/products?limit=5"

# Idempotent POST
curl -X POST -H "Idempotency-Key: order-123" \
  -H "Content-Type: application/json" \
  -d '{"product": "laptop"}' \
  "https://api.mockly.codes/orders"

Response Format

Collection (GET /{resource})

{
  "data": [
    { "id": 1, "name": "Laptop", "price": 999.99 },
    { "id": 2, "name": "Phone", "price": 499.99 }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "total_pages": 10
  }
}

Single item (GET /{resource}/42)

{
  "id": 42,
  "name": "Laptop",
  "price": 999.99,
  "category": "Electronics",
  "in_stock": true,
  "rating": 4.5
}

Response Headers

HeaderValueDescription
X-CacheHIT / MISS / BYPASSCache status for the response
X-Total-CountintegerTotal number of items available (collection endpoints)
X-Request-IDstringRequest trace ID (echoed or generated)

Code Examples

JavaScript / TypeScript

// Fetch with pagination
const res = await fetch('https://api.mockly.codes/products?page=1&limit=20&sort=price&order=asc')
const { data, pagination } = await res.json()
console.log(`Got ${data.length} of ${pagination.total} items`)

// Search
const search = await fetch(`https://api.mockly.codes/products?q=${encodeURIComponent('laptop')}&limit=10`)
const results = await search.json()

// User template (API key)
const tmpl = await fetch('https://api.mockly.codes/t/your-template-id', {
  headers: { Authorization: 'Bearer mk_your_key' }
})
const { data: items } = await tmpl.json()

Python

import requests

# Paginated + sorted
r = requests.get('https://api.mockly.codes/products', params={
    'page': 1, 'limit': 20, 'sort': 'price', 'order': 'asc'
})
data = r.json()
print(f"Total: {data['pagination']['total']}")

# Search specific fields
r = requests.get('https://api.mockly.codes/products', params={
    'q': 'laptop', 'search_fields': 'name,description', 'limit': 5
})

# User template
r = requests.get('https://api.mockly.codes/t/your-template-id',
    headers={'Authorization': 'Bearer mk_your_key'}
)

Go

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET",
        "https://api.mockly.codes/products?limit=10&sort=price&order=desc", nil)

    // For user templates, add auth header:
    // req.Header.Set("Authorization", "Bearer mk_your_key")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]any
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result)
}

All Resources

100 resources across 14 categories. All accessible at GET https://api.mockly.codes/{resource}.

Click any resource to open its interactive documentation.

Limits & CORS

No Rate LimitsMockly is free with unlimited requests — no throttling, no quotas. Use it in CI, load tests, or high-frequency dev scenarios.
CORS Fully OpenAll origins, methods, and headers are allowed. Works from any browser, Postman, or cURL without extra config.

What Mockly cannot do

  • Data is not persisted — POST/PUT/PATCH/DELETE requests are accepted but state is never modified
  • Cannot JOIN or query across multiple resources in one request
  • No GraphQL, WebSockets, or streaming endpoints
  • Generated data is deterministic per cache key — bypass with ?skip_cache=true for different data

Use with AI

Mockly provides machine-readable documentation specifically for LLM-based tools (GitHub Copilot, ChatGPT, Claude, Cursor, etc.).

llms.txt

Concise structured reference — paste this URL into any AI tool to give it full context on Mockly.

mockly.codes/llms.txt
llms-full.txt

Complete API reference including all examples — best for deep code generation tasks.

mockly.codes/llms-full.txt

Example AI prompts

React hook

Using the Mockly API (https://api.mockly.codes), write a React hook that fetches paginated products with search and sorting. Use https://www.mockly.codes/llms.txt for the full API reference.

Python data loader

Using the Mockly API (base URL: https://api.mockly.codes), write a Python function that loads all users across pages and returns a pandas DataFrame. No auth needed.

Testing harness

Write a Jest test suite that uses the Mockly API (https://api.mockly.codes/products) to verify pagination, sorting, and filtering work correctly in a frontend component.