API Documentation

📌 Key Features:

• One broker key via x-api-key (or Authorization: Bearer ...)
• Listings are always attributed to the key owner
• Create supports a safe dryRun mode (no write)
• Owner-only updates and mark-as-sold

Recommended headers: Send x-api-version: v1 on all requests. You can also send your own x-request-id (optional) and the API will echo it back as X-Request-Id. Include that request id when contacting support.

Idempotency: For POST /api/v1/create (non-dryRun), you can send x-idempotency-key to safely retry without double-creating.

Photos vs Media: Listings use top-level photos and featuredPhoto. The optional media object is used for videos and the media enhancement pipeline. You can omit media.photos; the API will mirror photos into it.

Broker listings only: Auction/marketplace and Voyage Photography fields are not part of the broker API contract.

Quick start (fetch all active listings):

Use /api/v1/search with no filters. By default it returns active listings across SportFishTrader (scope: all). Use cursor pagination to pull the full catalog.

curl -X GET "https://www.sportfishtrader.com/api/v1/search?sort=createdat_desc&limit=25" \
+  -H "x-api-key: YOUR_BROKER_API_KEY_HERE" \
+  -H "x-api-version: v1"

let cursor;
const all = [];

while (true) {
  const url = new URL('https://www.sportfishtrader.com/api/v1/search');
  url.searchParams.set('sort', 'createdat_desc');
  url.searchParams.set('limit', '25');
  if (cursor) url.searchParams.set('cursor', cursor);

  const res = await fetch(url.toString(), {
    headers: {
      'x-api-key': 'YOUR_BROKER_API_KEY_HERE',
      'x-api-version': 'v1',
    },
  });

  const data = await res.json();
  if (!res.ok) throw new Error(JSON.stringify(data));

  all.push(...(data.listings ?? []));
  cursor = data.pagination?.nextCursor;
  if (!cursor) break;
}

console.log('Total listings:', all.length);

Two common use cases:

• Marketplace embeds: use scope=all to show SportFishTrader's active listings with optional filters.
• Your inventory search: use scope=mine to search only listings you own.

The endpoint uses cursor pagination (no offsets). To fetch the next page, pass the returned pagination.nextCursor back as ?cursor=....

Keyword search: use q for fast prefix matching (e.g., q=viking 52). The backend converts your query into up to 10 tokens due to Firestore limits.

Example: /api/v1/search?scope=all&q=viking%2052&minPrice=500000&sort=createdat_desc&limit=25

Search gotchas:

• q is an OR across tokens (Firestore array-contains-any), so q=viking 52 matches listings containing either token.
• Very short terms may be ignored; use 3+ characters for best results (2-char state codes like FL are ok).
• Some combinations of q + filters + sort require a Firestore composite index. If you see INDEX_REQUIRED, remove filters or switch to sort=createdat_desc. After an index is deployed, it can take a few minutes to finish building—retry the request.

Tip: Every response includes an X-Request-Id header. For debugging, log it and include it when contacting support.

Errors are returned as a structured JSON payload:

{
  "code": "RATE_001",
  "error": "Rate Limit Exceeded",
  "message": "You have exceeded your API rate limit of 300 requests.",
  "suggestion": "Your rate limit will reset at 2026-02-01T12:00:00.000Z. Consider implementing request queuing or caching to reduce API calls.",
  "requestId": "d3c6c6b9-0b7c-4e12-a5a2-...",
  "status": 429,
  "endpoint": "createListingApi",
  "method": "POST",
  "timestamp": "2026-02-01T11:14:53.000Z"
}

When rate limiting is enabled, responses also include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.