API Documentation

Base URL: https://fakeapi.dev/api/v1

Getting Started

No authentication required for GET requests. Just hit the endpoint and receive JSON.

# curl
curl "https://fakeapi.dev/api/v1/users?per_page=5"

All responses follow this envelope shape:

{
  "success": true,
  "data": [...],
  "meta": {
    "total":       1000,
    "page":        1,
    "per_page":    10,
    "total_pages": 100,
    "has_more":    true
  }
}

Users

GET /api/v1/users

Returns paginated list of fake users.

Query Parameters
Param Type Description
page integer Page number (default: 1)
per_page integer Results per page (max 100)
locale string en_US, pl_PL, ar_SA, hi_IN, fr_FR
gender string male or female
search string Search first_name, last_name, email
fields string Comma-separated fields to return
sort_by string id, first_name, last_name, email, created_at
sort_dir string asc or desc
Try it → https://fakeapi.dev/api/v1/users?per_page=3&locale=en_US
GET /api/v1/users/{id}

Get a single user by ID.

Try it → https://fakeapi.dev/api/v1/users/1
GET /api/v1/users/{id}/posts

Get paginated posts for a user.

Try it → https://fakeapi.dev/api/v1/users/1/posts
GET /api/v1/users/{id}/orders

Get paginated orders for a user.

Try it → https://fakeapi.dev/api/v1/users/1/orders
POST /api/v1/users

Echo back a new user (nothing written to DB).

PUT /api/v1/users/{id}

Echo back updated user data.

DELETE /api/v1/users/{id}

Echo deletion success.

Products

GET /api/v1/products

Returns paginated list of products with category.

Query Parameters
Param Type Description
category string Category slug (electronics, clothing, etc.)
min_price number Minimum price filter
max_price number Maximum price filter
brand string Brand name filter
availability string in_stock, low_stock, out_of_stock
min_rating number Minimum rating (1–5)
search string Search by title
sort_by string id, price, rating, title, created_at
Try it → https://fakeapi.dev/api/v1/products?category=electronics&sort_by=price&sort_dir=desc
GET /api/v1/products/search

Search products by title or brand with ?q=term.

Query Parameters
Param Type Description
q string Search query
Try it → https://fakeapi.dev/api/v1/products/search?q=phone
GET /api/v1/products/{id}

Get a single product by ID.

Try it → https://fakeapi.dev/api/v1/products/1
GET /api/v1/products/{id}/reviews

Get paginated reviews for a product.

Try it → https://fakeapi.dev/api/v1/products/1/reviews

Categories

GET /api/v1/categories

Returns all product categories with product count.

Try it → https://fakeapi.dev/api/v1/categories
GET /api/v1/categories/{slug}

Get a single category by slug.

Try it → https://fakeapi.dev/api/v1/categories/electronics
GET /api/v1/categories/{slug}/products

Get paginated products in a category.

Try it → https://fakeapi.dev/api/v1/categories/electronics/products

Orders

GET /api/v1/orders

Returns paginated list of orders.

Query Parameters
Param Type Description
status string pending, processing, shipped, delivered, cancelled
payment_status string paid, pending, failed
user_id integer Filter by user ID
Try it → https://fakeapi.dev/api/v1/orders?status=delivered
GET /api/v1/orders/{id}

Get a single order by ID.

Try it → https://fakeapi.dev/api/v1/orders/1

Posts

GET /api/v1/posts

Returns paginated list of posts.

Query Parameters
Param Type Description
user_id integer Filter by author
visibility string public, friends, private
sort_by string id, likes_count, comments_count, created_at
Try it → https://fakeapi.dev/api/v1/posts?sort_by=likes_count&sort_dir=desc
GET /api/v1/posts/{id}/comments

Get paginated comments on a post.

Try it → https://fakeapi.dev/api/v1/posts/1/comments

Comments

GET /api/v1/comments

Returns paginated list of comments.

Query Parameters
Param Type Description
post_id integer Filter by post ID
user_id integer Filter by user ID
Try it → https://fakeapi.dev/api/v1/comments?per_page=10
GET /api/v1/comments/{id}

Get a single comment by ID.

Try it → https://fakeapi.dev/api/v1/comments/1

Reviews

GET /api/v1/reviews

Returns paginated list of reviews.

Query Parameters
Param Type Description
product_id integer Filter by product ID
min_rating number Minimum rating (1–5)
max_rating number Maximum rating (1–5)
Try it → https://fakeapi.dev/api/v1/reviews?min_rating=4
GET /api/v1/reviews/{id}

Get a single review by ID.

Try it → https://fakeapi.dev/api/v1/reviews/1

Countries

GET /api/v1/countries

Returns paginated list of countries with ISO codes, flags, currencies, phone codes and coordinates.

Query Parameters
Param Type Description
region string Africa, Americas, Asia, Europe, Oceania
subregion string Southern Asia, Western Europe, etc.
currency string ISO 4217 currency code (USD, EUR, GBP…)
search string Search by name, iso2 or iso3
sort_by string id, name, population, area_km2
Try it → https://fakeapi.dev/api/v1/countries?region=Asia&sort_by=population&sort_dir=desc
GET /api/v1/countries/{iso2}

Get a single country by ISO2, ISO3 or numeric ID.

Try it → https://fakeapi.dev/api/v1/countries/US
GET /api/v1/countries/{iso2}/cities

Get paginated cities for a country.

Query Parameters
Param Type Description
capitals_only boolean Return only capital cities (true/false)
sort_by string id, name, population
Try it → https://fakeapi.dev/api/v1/countries/US/cities?sort_by=population&sort_dir=desc

Cities

GET /api/v1/cities

Returns paginated list of cities with coordinates, timezone and population.

Query Parameters
Param Type Description
country string ISO2 or ISO3 country code
timezone string IANA timezone (e.g. America/New_York)
capitals_only boolean Return only capital cities
search string Search by city name
sort_by string id, name, population
Try it → https://fakeapi.dev/api/v1/cities?country=GB&sort_by=population&sort_dir=desc
GET /api/v1/cities/{id}

Get a single city by ID (includes nested country).

Try it → https://fakeapi.dev/api/v1/cities/1

Regions & Timezones

GET /api/v1/regions

Returns all geographic regions and subregions with country/population aggregates.

Try it → https://fakeapi.dev/api/v1/regions
GET /api/v1/timezones

Returns all IANA timezones with UTC offset.

Try it → https://fakeapi.dev/api/v1/timezones

Companies

GET /api/v1/companies

Returns paginated list of companies with industry, size, revenue, tech stack and benefits.

Query Parameters
Param Type Description
industry string Technology, Finance, Healthcare, Retail…
type string public, private, nonprofit, government
size string 1-10, 11-50, 51-200, 201-500, 501-1000, 1000+
country string Filter by headquarters country
search string Search by name, industry, description
sort_by string id, name, founded, rating, employee_count, annual_revenue_usd
Try it → https://fakeapi.dev/api/v1/companies?industry=Technology&size=1000%2B
GET /api/v1/companies/{id}

Get a single company by ID or slug.

Try it → https://fakeapi.dev/api/v1/companies/1
GET /api/v1/companies/{id}/departments

Get departments belonging to a company.

Try it → https://fakeapi.dev/api/v1/companies/1/departments
GET /api/v1/companies/{id}/employees

Get employees at a company.

Query Parameters
Param Type Description
department string Filter by department name
level string junior, mid, senior, lead, manager, director, vp, c-level
Try it → https://fakeapi.dev/api/v1/companies/1/employees?level=senior
GET /api/v1/companies/{id}/jobs

Get open job listings for a company.

Try it → https://fakeapi.dev/api/v1/companies/1/jobs

Employees

GET /api/v1/employees

Returns paginated list of employees with company, department, salary, skills and hire date.

Query Parameters
Param Type Description
level string junior, mid, senior, lead, manager, director, vp, c-level
employment_type string full-time, part-time, contract, intern
status string active, inactive, on-leave, terminated
remote boolean true or false
search string Search by name, job title, email
sort_by string id, first_name, last_name, salary, hire_date
Try it → https://fakeapi.dev/api/v1/employees?level=senior&remote=true
GET /api/v1/employees/{id}

Get a single employee (includes company and department).

Try it → https://fakeapi.dev/api/v1/employees/1
POST /api/v1/employees

Echo a new employee (nothing written to DB).

PUT /api/v1/employees/{id}

Echo updated employee data.

DELETE /api/v1/employees/{id}

Echo deletion success.

Jobs

GET /api/v1/jobs

Returns paginated open job listings with salary ranges, required skills and company info.

Query Parameters
Param Type Description
level string junior, mid, senior, lead, manager, director
employment_type string full-time, part-time, contract, intern
remote boolean true or false
status string open (default), closed, paused, draft
min_salary number Minimum salary_min filter
max_salary number Maximum salary_max filter
search string Search by title, description
sort_by string id, title, salary_min, salary_max, posted_at, applicants_count
Try it → https://fakeapi.dev/api/v1/jobs?level=senior&remote=true&min_salary=120000
GET /api/v1/jobs/{id}

Get a single job by ID or slug (includes company and department).

Try it → https://fakeapi.dev/api/v1/jobs/1
POST /api/v1/jobs

Echo a new job listing (nothing written to DB).

PUT /api/v1/jobs/{id}

Echo updated job data.

DELETE /api/v1/jobs/{id}

Echo deletion success.

Departments

GET /api/v1/departments

Returns paginated list of departments with headcount and budget.

Query Parameters
Param Type Description
search string Search by department name
Try it → https://fakeapi.dev/api/v1/departments?per_page=20
GET /api/v1/departments/{id}

Get a single department by ID (includes company).

Try it → https://fakeapi.dev/api/v1/departments/1

Charges (Payments)

Stripe-inspired payment charges with status, fee breakdown, refund and dispute flags.

GET /api/v1/payments

Returns paginated list of payment charges with nested payment method and user.

Query Parameters
Param Type Description
status string pending, succeeded, failed, refunded, disputed
currency string USD, EUR, GBP…
min_amount number Minimum charge amount
max_amount number Maximum charge amount
disputed boolean true or false
sort_by string id, amount, created_at, paid_at
Try it → https://fakeapi.dev/api/v1/payments?status=succeeded&currency=USD
GET /api/v1/payments/{id}

Get a single charge by ID.

Try it → https://fakeapi.dev/api/v1/payments/1
POST /api/v1/payments

Echo a new charge with fee and net calculation (nothing written to DB).

Query Parameters
Param Type Description
amount number Required. Charge amount (min 0.50)
currency string ISO 4217 code (default: USD)
user_id integer Required.

Payment Methods

GET /api/v1/payment-methods

Returns paginated list of saved payment methods (cards, bank accounts, wallets).

Query Parameters
Param Type Description
type string card, bank_account, paypal, apple_pay, google_pay
Try it → https://fakeapi.dev/api/v1/payment-methods?type=card
GET /api/v1/payment-methods/{id}

Get a single payment method by ID.

Try it → https://fakeapi.dev/api/v1/payment-methods/1

Invoices

GET /api/v1/invoices

Returns paginated invoices with line items, tax, discount, billing info and payment status.

Query Parameters
Param Type Description
status string draft, open, paid, void, uncollectible
currency string USD, EUR, GBP…
sort_by string id, total, due_date, created_at
Try it → https://fakeapi.dev/api/v1/invoices?status=paid&sort_by=total&sort_dir=desc
GET /api/v1/invoices/{id}

Get a single invoice by ID or invoice number (e.g. INV-000042).

Try it → https://fakeapi.dev/api/v1/invoices/1
POST /api/v1/invoices

Echo a new invoice with automatic subtotal/tax/total calculation (nothing written to DB).

Query Parameters
Param Type Description
user_id integer Required.
line_items array Required. Array of {description, quantity, unit_price}

Subscriptions

GET /api/v1/subscriptions

Returns paginated subscriptions with plan details, billing cycle, trial and cancellation info.

Query Parameters
Param Type Description
status string active, trialing, past_due, canceled, unpaid, paused
plan string Filter by plan name (starter, pro, business, enterprise…)
interval string month or year
sort_by string id, amount, created_at, current_period_end
Try it → https://fakeapi.dev/api/v1/subscriptions?status=active&interval=month
GET /api/v1/subscriptions/{id}

Get a single subscription by ID or subscription_id (sub_xxxx).

Try it → https://fakeapi.dev/api/v1/subscriptions/1
DELETE /api/v1/subscriptions/{id}

Echo cancel at period end (nothing written to DB).

Coupons

GET /api/v1/coupons

Returns paginated list of discount coupons.

Query Parameters
Param Type Description
active boolean true or false
discount_type string percent or fixed
Try it → https://fakeapi.dev/api/v1/coupons?active=true
GET /api/v1/coupons/{code}

Get a coupon by code (e.g. SAVE20) or ID.

Try it → https://fakeapi.dev/api/v1/coupons/SAVE20
GET /api/v1/coupons/{code}/validate

Validate a coupon — checks active status, expiry and redemption limit.

Try it → https://fakeapi.dev/api/v1/coupons/SAVE20/validate

Webhooks

Simulate Stripe-style webhook deliveries to any URL you control. Useful for testing webhook handlers, middleware, and signature verification without a live integration.

Every delivery includes an X-FakeAPI-Signature header with a Stripe-compatible HMAC-SHA256 signature: t={timestamp},v1={hash}.

GET /api/v1/webhooks/events

Returns the full list of supported event types.

Try it → https://fakeapi.dev/api/v1/webhooks/events
POST /api/v1/webhooks/simulate

Delivers a signed fake webhook payload to the URL you provide. Returns the HTTP status and body your server responded with.

Query Parameters
Param Type Description
url string Required. The HTTPS endpoint to POST to
event string Required. One of the supported event types (see /webhooks/events) 
# Simulate a payment.succeeded event
curl -X POST "https://fakeapi.dev/api/v1/webhooks/simulate" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.com/webhook","event":"payment.succeeded"}'

Supported event types:

payment.succeeded    payment.failed         payment.refunded
invoice.paid         invoice.payment_failed
subscription.created subscription.canceled  subscription.updated
user.created
order.created        order.shipped          order.delivered
coupon.redeemed

GraphQL

A lightweight GraphQL-compatible read API — no external packages, built from scratch. Supports field selection, filtering, pagination, and nested relations. Base URL: https://fakeapi.dev/api/graphql

Send queries via GET with ?query={...} or POST with a JSON body {"query":"..."}.

GET /api/v1/api/graphql?query={...}

Execute a GraphQL query via query string.

Query Parameters
Param Type Description
query string The GraphQL query
delay integer Optional response delay in ms
Try it → https://fakeapi.dev/api/graphql?query={users(per_page:3,locale:"en_US"){id first_name email}}
POST /api/v1/api/graphql

Execute a GraphQL query via JSON body.

Query Parameters
Param Type Description
query string Required. The GraphQL query
GET /api/v1/api/graphql/schema

Returns the full schema — all 34 query types with their filters and available relations.

Try it → https://fakeapi.dev/api/graphql/schema

Example queries:

# Select specific fields, filter + paginate
{
  users(per_page: 5, locale: "en_US") {
    id first_name email
  }
}

# Nested relations
{
  products(category: "electronics", per_page: 3) {
    id title price
    category { name slug }
  }
}

# Multiple top-level queries in one request
{
  users(per_page: 2) { id first_name }
  products(per_page: 2) { id title price }
  countries(region: "Asia") { name iso2 }
}

# Single record lookup
{
  user(id: 1) { id first_name last_name email }
  product(id: 5) { id title price brand }
}

All 34 available query types: users user products product categories category orders order posts post comments comment reviews review countries country cities city companies company departments department employees employee jobs job payments payment paymentMethods invoices invoice subscriptions subscription coupons coupon

Responses follow the standard GraphQL envelope: {"data":{...},"errors":[...]}. List queries include a meta key with pagination info. Use the GraphQL Explorer → to try it interactively.

Global Query Parameters

Parameter Example Description
page ?page=2 Page number
per_page ?per_page=25 Results per page (max 100)
delay ?delay=2000 Simulate slow network (ms, max 5000)
fields ?fields=id,name,email Return only specified fields
sort_by ?sort_by=price Field to sort by
sort_dir ?sort_dir=desc asc or desc
api_key ?api_key=xxx Your API key for higher limits

Rate Limiting

🆓
Free (IP-based)

100 requests / hour per IP address. No signup needed.

🔑
API Key

1,000 requests / hour with a free API key. Get yours →

Rate limit headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.