ThreadzSocial
Log in
Developers

Overview

v1

API overview

Welcome to the ThreadzSocial public API. This guide gets you from zero to a successful authenticated request — then points you to listings, closets, sandbox rules, and go-live.

What you can do

  • Read the marketplace — list and fetch live listings, open public closets (no key required for public GETs).
  • Prove identity — GET /me with a Bearer API key.
  • Manage inventory — create, update, and archive your listings (POST / PATCH / DELETE). Sandbox first; production after milestones.

Base URL

Production API base (all examples use this host):

https://www.threadzsocial.com/api/v1

For local Next.js: use http://localhost:3000/api/v1 with the same paths.

Response envelope

Every successful response looks like:

Success
{
  "data": { },
  "meta": { "version": "v1" }
}

Errors always look like:

Error
{
  "error": {
    "code": "validation_error",
    "message": "Human-readable explanation",
    "details": { }
  }
}

Full code table: Errors.

Quickstart

  1. Create a ThreadzSocial account.
  2. Register an app on /developers/apps and accept the API Terms.
  3. Create a sandbox key on that app. Copy it once — we only show the full secret at creation.
  4. Hit health, then /me, then create a sandbox listing.

1. Health (no key)

curl
curl -sS https://www.threadzsocial.com/api/v1/health

2. Authenticated me

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

3. Browse live listings (public)

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

Sandbox vs Discover

Sandbox keys only create and manage sandbox listings. Those items never appear on public Discover. Anonymous listing GETs return live data only; a sandbox Bearer on GET /listings returns your sandbox inventory. Details: Sandbox.

Auth at a glance

  • Header: Authorization: Bearer <api_key>
  • Format: stz_{live|sandbox}_{12hex}_{48hex}
  • Default scopes: read, listings:write.

Deep dive: Authentication.

Rate limits

Soft limits (headers when auth middleware runs): anonymous ≈ 120 req/min, keyed ≈ 600 req/min. Exceeding returns 429 rate_limited. Limits may tighten in production.

Next steps