API Reference

1Authentication

All API requests require authentication via API Key. Include your API key in the X-API-Key header.

X-API-Key: YOUR_API_KEY

You can create and manage API keys from your Dashboard. Free tier users get 1 API key, Pro users get unlimited keys with granular permissions.

2Endpoints (Bins)

A "bin" is a mock JSON endpoint with persistent storage. Each bin has a unique ID and can store any valid JSON payload.

Create a Bin

POST /api/bins

curl -X POST https://mockjsonapi.com/api/bins \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "users", "data": {"users": [{"id": 1, "name": "John"}]}, "isPublic": true, "expiresIn": 30}'

Request Body

Response

{
  "success": true,
  "bin": {
    "id": "abc123def456",
    "name": "users",
    "userId": "user_123",
    "isPublic": true,
    "sizeBytes": 1024,
    "version": 1,
    "accessCount": 0,
    "expiresAt": "2026-02-14T10:30:00Z",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T10:30:00Z"
  },
  "url": "https://mockjsonapi.com/bin/abc123def456"
}

List Your Bins

GET /api/bins

Supports pagination via page and pageSize query parameters. Filter by name (or q), public (true/false), and scope (admin only: "all").

Get a Bin

GET /api/bin/:id

Returns the bin data and metadata. Public bins can be accessed without authentication. Response includes { data, meta: { bin, rateLimit } } with CORS headers, ETag, and rate limit headers.

Update a Bin

PUT /api/bin/:id

Updates the bin data and creates a new version. Returns the updated bin with new version info.

Request Body

API Key Auth (x-api-key header): Only data field allowed. name and isPublic are locked.

Session Auth (Dashboard): Supports data, name, isPublic. Visibility-only toggles (no data change) are allowed.

curl -X PUT https://mockjsonapi.com/api/bin/abc123def456 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": {"users": [{"id": 1, "name": "John"}, {"id": 2, "name": "Jane"}]}}'

Delete a Bin

DELETE /api/bin/:id

Permanently deletes the bin and all its versions. This action cannot be undone.

API Key Auth: DELETE blocked on public bins. Use private bins for write access via API.

curl -X DELETE https://mockjsonapi.com/api/bin/abc123def456 \
  -H "X-API-Key: YOUR_API_KEY"

Bin Versions

GET /api/bin/:id/versions

Lists all versions of a bin (max 20). Each update creates a new version for rollback capability. Returns { versions: [...], total } with current version marked.

POST /api/bin/:id/versions — Rollback to a specific version:

curl -X POST https://mockjsonapi.com/api/bin/abc123def456/versions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"versionId": "v1"}'

3Public Access (No Auth)

Public bins can be accessed without an API key via the public URL:

GET https://mockjsonapi.com/bin/abc123def456

This is ideal for frontend prototyping — just share the URL with your team or use it directly in your application during development.

Response includes CORS headers (Access-Control-Allow-Origin: *), caching (Cache-Control: public, max-age=30), and ETag.

4Rate Limits

Daily request limits per tier (reset at midnight UTC). Rate limit headers included in all responses.

Rate limit headers included in all responses: X-RateLimit-Limit,X-RateLimit-Remaining.

5Error Codes

All errors return { success: false, error: "message", meta?: { rateLimit: {...} } }.