Sandbox environment

Build and test integrations safely. Sandbox uses the same API surface as production but keeps test inventory isolated from real buyers and Discover.

Core rules

• Sandbox keys only touch sandbox listings. Creates, updates, and deletes with a stz_sandbox_… key set api_environment = sandbox on those resources.
• Public Discover is live-only. The consumer feed, SEO surfaces, and anonymous GET /listings never return sandbox items.
• Same base path. There is no separate sandbox host in v1 — environment is determined by the key (and stored listing field), not by a different domain.
• No real money. Do not treat sandbox inventory as sellable stock.

Getting a sandbox key

1. Sign in and open /developers/apps.
2. Register an app (or open an existing one).
3. Create a key with environment sandbox.
4. Store the secret; we cannot show it again.

Verify sandbox auth

curl -sS \
  -H "Authorization: Bearer stz_sandbox_YOUR_KEY" \
  https://www.threadzsocial.com/api/v1/me

A successful response includes api_key.environment: "sandbox". Completing this call is a go-live milestone (sandbox_me).

Sandbox Hub (web UI)

After you push sandbox listings, open /developers/sandbox while signed in as the key owner. You get at-a-glance counts, status filters, and a photo grid of your sandbox inventory. These rows never appear on Discover or the public live feed.

How GET /listings behaves

• No key (anonymous) — live active Discover feed only.
• Sandbox key — your own sandbox listings only (meta.environment = sandbox). You will not see the public live feed with a sandbox Bearer.
• Live key — public live feed (same marketplace data).

curl -sS "https://www.threadzsocial.com/api/v1/listings?limit=5"

curl -sS "https://www.threadzsocial.com/api/v1/listings?limit=5" \
  -H "Authorization: Bearer stz_sandbox_YOUR_KEY"

Create sandbox inventory with POST /listings, or bulk with POST /listings/batch (max 25 items per request).

POST /listings/batch

Upsert many listings in one call. Requires Bearer + listings:write. Body: { "items": [ /* 1–25 listing objects */ ] }. Same fields as POST /listings per item (including external_id for idempotent upserts).

• Max 25 items per request (max_per_request in response meta).
• Partial success: each index returns ok + listing or error. Meta includes created, updated, failed.
• HTTP 200 when any item succeeds; 422 when every item fails; 400 for invalid body.

curl -sS -X POST https://www.threadzsocial.com/api/v1/listings/batch \
  -H "Authorization: Bearer stz_sandbox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "title": "Sandbox tee",
        "price_cents": 1500,
        "status": "draft",
        "external_id": "sku-tee-1"
      },
      {
        "title": "Sandbox jacket",
        "price_cents": 4200,
        "status": "draft",
        "external_id": "sku-jkt-1"
      }
    ]
  }'

Then open Sandbox Hub to confirm they appear.

Milestones that use sandbox

Full checklist and production unlock: Go live.

Data hygiene

• Prefer realistic but non-PII test content.
• Use external_id on creates for idempotent retries in sandbox and production.
• Archive sandbox listings when you are done testing.