Quick Start

Mock Alpha is available as a hosted instance at:

https://mock-alpha.duckdns.org

No local setup required — all examples throughout the docs use this URL. Self-hosting is not supported; the team shares this single instance.

1. Create an account

Open https://mock-alpha.duckdns.org in a browser and click Register. You will be redirected to the dashboard after signing in.

2. Create a project

Create a project (e.g., "My App")
Copy the generated API key from the project settings
Note the project ID from the URL

Projects support multi-user collaboration — invite teammates from the project settings so everyone can manage the same endpoints and scenarios.

3. Connect your app

Two options, from simplest to most automated:

Option A — point your base URL at Mock Alpha

Change your app's API base URL (in your debug/dev build config) to:

https://mock-alpha.duckdns.org/api/mock

and send the API key with every request:

X-Api-Key: <your-api-key>

Your app's request GET /users/123 now becomes GET https://mock-alpha.duckdns.org/api/mock/users/123 and returns whatever scenario you selected in the dashboard. Works on any platform with zero extra code.

Shorter URLs: the mock server also answers on /api/<path> directly, e.g. https://mock-alpha.duckdns.org/api/users/123. The only exception is paths whose first segment collides with an internal prefix (auth, collect, invitations, mock, projects) — those remain reachable via /api/mock/<path> only. The dashboard warns you when you create such a path.

Option B — add an interceptor

An interceptor forwards traffic to your real backend, reports the responses to Mock Alpha so endpoints are captured and seeded automatically, and serves the mock response back to your app.

Android Interceptor — full OkHttp reference implementation
Platform Examples — Flutter (Dio), Web (axios), iOS (URLSession), curl

See Client Integration for the underlying protocol if you want to build one for another platform.

4. Seed your first endpoint

If you used Option B, just navigate around your app — endpoints appear in the dashboard automatically as traffic flows.

If you used Option A, seed an endpoint manually with a single request:

curl -X POST https://mock-alpha.duckdns.org/api/collect \
  -H "X-Api-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "path": "/users/123",
    "statusCode": 200,
    "responseBody": { "id": "123", "name": "Alex" },
    "serviceName": "my-app"
  }'

The endpoint now exists in the dashboard, and its success scenario is seeded with that response body (sensitive fields masked). Captures with a non-2xx status, and captures for endpoints that already exist, only update the endpoint's snapshot — edit scenarios from the dashboard in that case.

5. Switch scenarios

Open the endpoint in the dashboard, add scenarios (e.g., error-500, empty-list), and select which one is active. Your app gets the selected response on the next request — no client changes, no redeploys. See Mock Scenarios.

MQTT (optional)

For real-time event mocking, connect with:

TCP: mqtt://mock-alpha.duckdns.org:1883
WebSocket: ws://mock-alpha.duckdns.org:1884

Use your projectId as the username and apiKey as the password. See MQTT Mock Server for configuration.

Quick Start

On this page