Create one decision-ready Next Move.

Create, poll, receive

Only product_url is required. A new bounded scan returns 202. A suitable fresh, founder-reviewed result may return 200. Repeat the same idempotency key to receive the same request.

curl -X POST https://trendsfast.com/v1/next-move \
  -H "Authorization: Bearer tf_live_<prefix>.<secret>" \
  -H "Idempotency-Key: 4a2d1201-9666-4ef0-90a9-e5aa47786c8e" \
  -H "Content-Type: application/json" \
  -d '{
    "product_url": "https://example.com",
    "goal": "qualified_signups",
    "market": "US",
    "language": "en",
    "preferred_channels": ["x", "linkedin"]
  }'

HTTP/1.1 202 Accepted
Location: https://trendsfast.com/v1/next-moves/scan_01J...

{
  "id": "scan_01J...",
  "status": "QUEUED",
  "status_url": "https://trendsfast.com/v1/next-moves/scan_01J..."
}

GET /v1/next-moves/scan_01J...

{
  "status": "READY",
  "next_move": {
    "action": "PUBLISH",
    "channel": "x",
    "topic": "Evidence-first distribution agents",
    "confidence": 0.82,
    "valid_until": "<absolute ISO-8601 timestamp>"
  },
  "why_now": {
    "signal_class": "CORROBORATED_SIGNAL",
    "independent_source_count": 3
  },
  "evidence": [{ "url": "https://original.example/..." }],
  "founder_reviewed": true,
  "auto_publish": false
}

Authentication

Approved API users receive a unique project-scoped key with the form tf_live_<prefix>.<secret>. The raw secret is shown once; only a secure derived verifier and prefix are stored. Keys can expire, be rate-limited, revoked, and reissued.

The public free-scan form never exposes a reusable API key. A test-family key cannot authorize managed live processing, and a live-family key cannot authorize example processing.

Lifecycle

QUEUED → RUNNING → REVIEW_REQUIRED → READY, with explicit FAILED. Poll the returned status URL with the same Bearer key. A READY result is private by default, founder-reviewed, and always reports auto_publish=false.

Limits and cost admission

Scan creation is bounded by key, time window, provider-cost reservation, and the per-scan cost ceiling. Polling an existing result does not create another research run, but remains subject to normal abuse controls. “Unlimited agents” never means unlimited scan creation or provider fan-out.

Bounded errors

Agent workflow examples

The examples below all use HTTP. They are not claims of native connectors, plugins, or account integrations.

The runtime OpenAPI 3.1 document is served at GET /v1/openapi.json. Public API access remains approval-gated until a project key has been issued.