Skip to content
MirApi Docs

Quickstart Guide

Get your first resilient API call running in under 5 minutes.

Step 1: Get Your API Key

Section titled “Step 1: Get Your API Key”

Sign up at mirapi.io and open the dashboard. Create group and generate your first API key. Your key will look like:

Terminal window
export MIRAPI_KEY="la_5fa62960e7c9af7c***"

Step 2: Make Your First Proxy Request

Section titled “Step 2: Make Your First Proxy Request”

Send your request to https://proxy.mirapi.io/ and specify the destination URL in the X-Target-URL header:

Terminal window
# Original direct call to Stripe
curl -X POST https://api.stripe.com/v1/customers \
  -H "Authorization: Bearer sk_live_..."


# The same call, proxied via MirApi
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/customers" \
  -H "X-Identity-Key: Bearer sk_live_..."

MirApi intercepts the request, verifies your key, strips the X-* proxy headers, injects Authorization: Bearer sk_live_... from X-Identity-Key, and forwards the request to Stripe. The Stripe response is returned to you unchanged.

Step 3: Add Resilience Headers

Section titled “Step 3: Add Resilience Headers”

Enhance your calls with retry logic, timeout, and smart caching:

Terminal window
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Identity-Key: Bearer sk_live_..." \
  -H "X-Retry-Count: 3" \
  -H "X-Retry-Delay: 100ms" \
  -H "X-Proxy-Timeout: 5s" \
  -H "X-Circuit-Breaker: on" \
  -H "X-Smart-Cache: 60s" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2000, "currency": "usd", "source": "tok_visa"}'

What happens step by step:

  1. Request arrives → your key is verified
  2. Body scanned for card numbers (none found → continues)
  3. Idempotency key auto-computed from SHA256(ClientID + TargetURL + Method + Body)
  4. Circuit breaker checked for api.stripe.com → currently CLOSED → proceeds
  5. Request forwarded to Stripe with a 5-second timeout
  6. If Stripe returns a 5xx or times out → retry up to 3 times with exponential backoff
  7. If all retries fail → check Smart Cache for a previous successful response for this exact request

Step 4: Verify the Response

Section titled “Step 4: Verify the Response”

If the request was rescued from cache, you’ll see the X-Rescued header:

HTTP/1.1 200 OK
X-Rescued: cache
Content-Type: application/json


{
  "id": "ch_3Pz9...",
  "status": "succeeded"
}

If the request succeeded on first try, no X-Rescued header is added — it’s only present when a rescue mechanism was used.

Step 5: Use a Pre-configured Route (Optional)

Section titled “Step 5: Use a Pre-configured Route (Optional)”

For complex multi-target scenarios, configure a route in your dashboard and use X-Route-Key instead of X-Target-URL:

Terminal window
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Route-Key: stripe-charges" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2000, "currency": "usd"}'

The route stripe-charges is configured in your dashboard with the target URL, timeout, body mapping rules, and response extraction rules — none of this needs to be in your headers.

Quick Reference — All Supported Headers

Section titled “Quick Reference — All Supported Headers”
HeaderExample ValueDescription
X-MirApi-Keyla_5fa629...Required. Your MirApi authentication key
X-Target-URLhttps://api.stripe.com/v1/chargesDestination API endpoint (required unless using X-Route-Key)
X-Route-Keystripe-chargesUse a pre-configured dashboard route instead of X-Target-URL
X-Identity-KeyBearer sk_live_...Forwarded as the Authorization header to the upstream (ephemeral — never stored)
X-Proxy-Master-Keymy-master-passphraseDecryption key for database-stored encrypted credentials
X-Retry-Count3Max retry attempts on 5xx or connection failure
X-Retry-Delay100msBase delay for exponential backoff (e.g., 100ms, 1s)
X-Proxy-Timeout5sPer-attempt timeout (e.g., 500ms, 5s, 30s)
X-Circuit-BreakeronEnable circuit breaker for the target host
X-Smart-Cache60sCache TTL for successful responses; used as fallback on failure
X-Failover-URLhttps://backup-api.com/v1/chargesSecondary endpoint if all retries to primary fail
X-Webhook-Callbackhttps://your-app.com/webhookEnable async mode — returns 202 Accepted, POSTs result to your callback
X-Proxy-Idempotency-Keyorder_789_attempt_1Custom idempotency key (auto-computed if omitted)
X-Extract-Redirect$.url || $.checkoutUrlExtracts the first found URL (supports fallback via
X-Extract-Map.id = >charge_id,.status = >data.stateRestructures the JSON response. Allows mapping multiple fields, creating nested objects, mapping arrays ([]), as well as applying value formatting templates (for example, id=>$.label(ID: {value}))
X-Credential-ID4a2e5d18-...Explicit credential UUID for X-Proxy-Master-Key lookup

Next Steps

Section titled “Next Steps”