Stubbr.dev

How It Works

Stubbr lets you write production-ready API calls from day one. Your request has two parts:

• Payload — The real data your backend will receive in production
• __instructions — Defines what Stubbr returns during development (ignored by your real backend)

When you switch to production, just change the API host. Your backend receives the payload and ignores __instructions.

Authentication

Include your token in every request using either method:

Authorization: Bearer YOUR_TOKEN

// or

X-API-Token: YOUR_TOKEN

Token endpoints:

• GET /api/__token/request?email=you@example.com — Get a new token
• GET /api/__token/recover?email=you@example.com — Recover existing token

One token per email. Tokens are deleted after 30 days of inactivity.

The __instructions Object

Control the response behavior:

{
  "order_id": 123,
  "__instructions": {
    "status": 201,
    "delay": 500,
    "headers": {
      "X-Request-Id": "abc-123"
    },
    "body": {
      "success": true,
      "order": {
        "__repeat": 1,
        "id": 123,
        "total": "?price",
        "created_at": "?dateTime"
      }
    }
  }
}

Generating Arrays with __repeat

Use __repeat inside __instructions.body to generate arrays:

{
  "__instructions": {
    "body": {
      "user": {
        "__repeat": 5,
        "id": "?counter",
        "name": "?name"
      }
    }
  }
}

// Returns:
{
  "users": [
    { "id": 0, "name": "John Doe" },
    { "id": 1, "name": "Jane Smith" },
    ...
  ]
}

Notes:

• The key is automatically pluralized (user → users)
• Use __as to override the output key name
• Maximum 20 items per array
• Maximum 2 levels of nesting
• ?counter increments globally across the entire response

UUID Mode with __uuid

Add "__uuid": true to a __repeat block to make ?id and ?uuid return UUID7 values:

{
  "__instructions": {
    "body": {
      "user": {
        "__repeat": 3,
        "__uuid": true,
        "id": "?id",
        "name": "?name"
      }
    }
  }
}

// Returns:
{
  "users": [
    { "id": "01932c5d-9e1f-7bc3-9e84-4f5a3b2c1d0e", "name": "John Doe" },
    { "id": "01932c5d-9e20-7a12-8b45-2d6e7f8a9b0c", "name": "Jane Smith" },
    { "id": "01932c5d-9e21-7d34-9c56-3e7f8a9b0c1d", "name": "Bob Wilson" }
  ]
}

UUID7 is time-ordered, making it ideal for database primary keys. The flag applies to the entire block and nested blocks.

All Placeholders

Use these inside __repeat blocks to generate fake data:

Personal

Company

Address

Numbers

Identifiers

Text

Internet

Date & Time

Other

Response Caching

Identical requests return cached responses. The cache key is based on:

• Your API token
• HTTP method
• Request path
• Query parameters
• Request body

This means generated fake data (names, emails, UUIDs, etc.) stays consistent for identical requests. This is useful for testing - you get the same response every time without randomness breaking your tests.

To get fresh data, either:

• Use "no_cache": true in __instructions
• Change something in the request (different body, query param, etc.)
• Clear your cache

Cached responses include the header __from_cache: true.

Clear your cache:

POST /api/__cache/clear
Authorization: Bearer YOUR_TOKEN

Rate Limiting

• API requests: 10 requests per second (per token)
• Token requests: 1 request per 10 seconds (per IP)

If you add a delay in __instructions, the rate limit window adjusts accordingly.

Limits

Error Responses