Sandbox

Every workspace has a sandbox. Use a test key and the API returns fixture data, charges nothing, and behaves identically in every other respect.

curl -X POST https://api.unif.dev/v1/products/search \
  -H "Authorization: Bearer unif_sk_test_8f3c1a9e4b2d8065f1a3c7e9b5d2408f" \
  -H "Content-Type: application/json" \
  -d '{ "market": "US", "period": { "preset": "last_30d" } }'

There is no separate base URL. The key prefix — unif_sk_test_ — decides the environment, so switching is a matter of changing one environment variable.

What is the same

The full schema

Same fields, same types, same envelope. A client written against the sandbox works unchanged against live data.

Validation and errors

Invalid parameters fail with the same codes. Coverage rules and filterability are enforced identically.

Pagination and jobs

Cursors work, jobs run through their statuses, and webhooks deliver with real signatures.

Rate limits

Enforced at the same thresholds, so you can exercise your backoff path.

What is different

	Sandbox
Data	A fixed fixture set of about 500 shops, 5,000 products and 2,000 creators
Credits	Never charged; `GET /usage` reports the live balance unchanged
Freshness	`meta.refreshed_at` is fixed to the fixture’s build date
Jobs	Complete in seconds regardless of size
Coverage	Mirrors `tiktok_shop` / `US` for every requested market

Fixture data is stable, not realistic. It is built so that assertions do not break, which means it will not reproduce data-shaped problems — a market with weekly-only granularity, a creator with a null agency, an ambiguous product. Test those against live data with a small budget before you ship.

Deterministic fixtures

The same request returns the same rows every time, so you can assert on values:

def test_search_returns_expected_shape():
    resp = client.post("/v1/products/search", json={
        "market": "US",
        "period": {"preset": "last_30d"},
        "filters": {"revenue": {"gte": 50000}},
        "sort": [{"field": "revenue", "direction": "desc"}],
        "limit": 10,
    })

    assert resp.status_code == 200
    body = resp.json()
    assert body["object"] == "list"
    assert len(body["data"]) == 10
    assert body["data"][0]["id"].startswith("prd_")
    assert body["data"][0]["metrics"]["revenue"] >= 50000

Known fixture IDs are listed in the dashboard under Settings → Sandbox, so you can write tests against a specific shop or product rather than whatever happens to rank first.

Exercising the paths that are hard to reach live

The fixture set includes entities that deliberately trigger each edge case.

To test	Use
`not_found`	`https://www.tiktok.com/shop/unif-fixture-missing`
`ambiguous`	`https://www.tiktok.com/shop/unif-fixture-ambiguous`
`partial` enrichment	`shp_00000000000000000000partial`
`job.failed`	A job with `"input": { "force_failure": true }`
`429`	Exceed the rate limit; it is enforced normally

def test_handles_not_found():
    resp = client.post("/v1/resolve", json={"inputs": [
        {"type": "shop", "url": "https://www.tiktok.com/shop/unif-fixture-missing", "ref": "x"}
    ]})

    result = resp.json()["data"][0]
    assert result["status"] == "not_found"
    assert result["id"] is None

Point CI at the sandbox and keep live keys out of it entirely. A test suite that spends credits will eventually spend a lot of them on a branch nobody merged.

Webhooks in the sandbox

Sandbox webhooks deliver real signed requests with their own secret, so your verification code is exercised properly. Register an endpoint with a test key and it fires on sandbox jobs and trackers only — sandbox events never reach a live endpoint, and vice versa.

Getting started

Core concepts

Workflows

Guides

Platform

Release notes

What is the same

The full schema

Validation and errors

Pagination and jobs

Rate limits

What is different

Deterministic fixtures

Exercising the paths that are hard to reach live

Webhooks in the sandbox

​What is the same

The full schema

Validation and errors

Pagination and jobs

Rate limits

​What is different

​Deterministic fixtures

​Exercising the paths that are hard to reach live

​Webhooks in the sandbox

What is the same

What is different

Deterministic fixtures

Exercising the paths that are hard to reach live

Webhooks in the sandbox