API ReferenceSandbox API

Sandbox API

Endpoints for managing sandbox state, generating test requests, and running controlled auction simulations.

Base URL: https://api.praevis.com Auth: X-API-Key: {YOUR_KEY}

All sandbox endpoints operate on sandbox data only — they do not affect production.

Reset sandbox data

POST /api/sandbox/reset

Flushes all sandbox metrics, auction logs, and Redis data for your partner account. Takes effect immediately.

Body: Empty.

Response:

{
  "message": "Sandbox data reset successfully",
  "affected_publishers": 3,
  "affected_dsps": 2
}

Use before a clean validation run to get a zero-baseline.

Generate a test bid request

GET /api/sandbox/test-bid

Returns a sample bid request JSON that your bidder can use for testing. Does not send anything to your endpoint.

Query params:

ParamValuesDefault
scenarioctv-uae-drama, mobile-uk-sport, web-us-news, ctv-timeoutctv-uae-drama

Response: Full OpenRTB 2.5 bid request JSON (see Test Data for full examples).

Send test bid to your endpoint

POST /api/sandbox/test-bid

Generates a bid request and sends it to your registered demand source (DSP) endpoint. Returns the full request, your response, and whether you won.

Body:

{
  "dsp_id": "{YOUR_DSP_ID}",
  "scenario": "ctv-uae-drama"
}

Response:

{
  "request": { ...bid request JSON... },
  "response_status": 200,
  "response_body": { ...your bid response... },
  "response_time_ms": 42,
  "outcome": "win",
  "clearing_price": 5.50,
  "floor": 3.00
}

outcome values: win, no-bid, below-floor, timeout, error.

Simulate an auction

POST /api/sandbox/simulate-auction

Runs a controlled auction with configurable parameters against a Delegate strategy. Does not require a live supply source (Publisher) or demand source (DSP) — pure simulation.

Body:

{
  "dsp_id": "{YOUR_DSP_ID}",
  "auction": {
    "device": {
      "devicetype": 3,
      "geo": {
        "country": "AE",
        "region": "AE-DU",
        "city": "Dubai"
      }
    },
    "content": {
      "genre": "drama"
    },
    "categories": ["IAB1"],
    "bidfloor": 3.00,
    "publisher_id": "optional-publisher-uuid"
  }
}

All auction fields are optional — omit any to use defaults.

Response (match found):

{
  "matched_rule": "CTV UAE Prime Time",
  "campaign_id": "campaign-001",
  "campaign_name": "CTV UAE Prime Time Campaign",
  "bid_cpm": 7.00,
  "base_cpm": 7.00,
  "won": true,
  "clearing_price": 7.00,
  "floor": 3.00,
  "reason": "campaign_match",
  "creative": {
    "vast_url": "https://cdn.example.com/vast.xml",
    "creative_id": "creative-001"
  },
  "conditions_evaluated": [
    { "campaign": "CTV UAE Prime Time", "rules": ["CTV UAE Prime Time"] }
  ]
}

Response (no match):

{
  "matched_rule": null,
  "campaign_id": null,
  "bid_cpm": 0,
  "won": false,
  "floor": 3.00,
  "message": "No rule matched the auction parameters. Check your campaign targeting.",
  "conditions_evaluated": [
    { "campaign": "CTV UAE Prime Time", "rules": ["CTV UAE Prime Time"] }
  ]
}

If matched_rule is null, no campaign rule matched the auction parameters. Check conditions_evaluated to see which campaigns exist.

Sandbox endpoint health

GET /api/sandbox/health

Returns status of sandbox infrastructure — useful if you’re seeing unexpected errors.

Response:

{
  "status": "ok",
  "sandbox_redis": "connected",
  "synthetic_dsps": ["HighBidder", "LowBidder", "RandomBidder", "TimeoutDSP"],
  "test_publishers_available": 4
}
Partner APIErrors & Status Codes