TopTrends API documentation
Create reliable HTTP, browser, stealth, batch, crawl, and scheduled collection workflows through one versioned API.
Quickstart
Create an API key in your Workspace, store it once, and send a direct-first scrape request.
The downloadable OpenAPI file is the machine-readable release contract for schemas, scopes, status codes, pagination, and examples.
curl --request POST https://toptrends.ai/v1/scrapes \
--header "Authorization: Bearer tt_live_REPLACE_ONCE" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: scrape-2026-08-09-001" \
--data '{
"url": "https://example.com/products",
"mode": "http",
"request": { "method": "GET" },
"output": { "formats": ["markdown", "json"] }
}'Core endpoint groups
Authentication and tenancy
Send API keys as Bearer tokens. Every key belongs to one Workspace, has explicit scopes, and cannot cross tenant boundaries. Revoked keys return 401 immediately.
Direct-first execution
HTTP, browser, and stealth modes use direct egress by default. Add a proxy policy only when the target requires it; actual proxy bytes and credits remain visible in job usage.
Reliable writes
Use Idempotency-Key for every create, cancel, retry, and schedule mutation. Reusing a key with the same payload replays the result; a different payload returns 409.
Pagination and status
List endpoints use opaque cursors. Poll a Job or consume its event stream until it reaches succeeded, partially_succeeded, failed, cancelled, or timed_out.
Results and artifacts
Results are paginated and immutable by revision. Artifact and export resources expose authenticated download URLs, media type, byte size, checksum, and retention metadata.
Webhooks
Workspace-scoped endpoints deliver signed, replay-safe job events. Verify the timestamped signature over the raw request body and deduplicate the event ID.
Errors and limits
Errors use application/problem+json with a stable code and request ID. Respect Retry-After and RateLimit headers. Validation errors never enqueue work or spend credits.