SportFishTrader — Premier Offshore Fishing Boat Marketplace

Introduction

Overview

Welcome to the SportFishTrader API documentation. Our RESTful API enables brokers and brokerages to seamlessly integrate their inventory management systems with the SportFishTrader platform.

With our API, you can programmatically create, update, and manage boat listings, synchronize your inventory in real-time, and automate your workflow to save time and reduce manual data entry.

Secure & Reliable

All API requests are made over HTTPS with API key authentication. Your data is always encrypted in transit.

Key Features

Real-time Sync

Instantly synchronize your inventory with SportFishTrader

Listing Management

Create, update, and manage boat listings programmatically

Secure Access

Industry-standard API key authentication

Data Validation

Automatic validation of all submitted data

Getting Started

Obtain an API Key
Purchase API access through the API Access page in your broker portal.
Configure Your Environment
Store your API key securely as an environment variable (never commit to version control).
Make Your First Request
Follow the examples below to start creating listings programmatically.
Test Thoroughly
Test all endpoints in a development environment before deploying to production.

Authentication

API Keys

All API requests require authentication using an API key. Your API key is unique to your brokerage or individual broker account and should be kept confidential.

How to Authenticate

Include your API key in the x-api-key header of every request:

HTTP Headers

x-api-key: your_api_key_here

Keep Your API Key Secure

Never commit API keys to version control
Store keys in environment variables or secure vaults
Rotate keys immediately if compromised
Use different keys for development and production

Security Best Practices

Always use HTTPS for API requests
Implement rate limiting on your side to avoid throttling
Validate and sanitize all data before sending to the API
Log API requests for audit purposes
Monitor for unusual activity or unauthorized access
Use IP whitelisting if available in your environment

API Endpoints

Base URL:https://us-central1-sportfishtrader-v5.cloudfunctions.net

POST

Create Listing

/createListingApi

Create a new boat listing on the SportFishTrader platform.

Request Headers

Header	Value	Required
`x-api-key`	Your API key	Yes
`Content-Type`	application/json	Yes

Request Body

The fields you can submit depend on your API key configuration. Below is the complete list of all available fields organized by category.

Field Configuration: Administrators configure which fields are required (must be present) and allowed (can be optionally included) for each API key in the Admin Portal. Required fields will return a 400 error if missing. Only allowed fields will be saved.

Core Identification Fields (Required)

Field	Type	Description	Example
`brokerId`	string	Individual broker UID (Firebase Auth)	"abc123def456"
`brokerageId`	string	Brokerage document ID (must match API key owner)	"brkg_xyz789"
`sellerId`	string	Seller UID (defaults to brokerId if not provided)	"seller123"

Listing Metadata

Field	Type	Description	Valid Values
`listingStatus`	string	Listing visibility and state	"draft", "pending_payment", "active", "expired", "terminated", "on_hold"
`listingType`	string	Type of listing	"standard", "featured", "premium"

Basic Boat Information

Field	Type	Description	Valid Values / Example
`condition`	string	Boat condition	"new", "used"
`year`	number	Year of manufacture	2020
`manufacturer`	string	Boat manufacturer/builder	"Yellowfin"
`model`	string	Boat model name	"42 Offshore"
`type`	string	Boat class/category	"Center Console", "Express", "Convertible", "Walk Around", "Other"

Pricing Information

Field	Type	Description	Example
`price`	number	Asking price in USD	725000
`contactForPrice`	boolean	Hide price, show "Contact for Price"	false
`reservePrice`	number	Minimum acceptable price (for auctions)	650000
`hasReserve`	boolean	Whether listing has a reserve price	true

Location

Field	Type	Description	Example
`locationCity`	string	City where boat is located	"Miami"
`locationState`	string	State/province (2-letter code)	"FL"
`locationZIP`	string	ZIP/postal code	"33139"

Boat Specifications

Field	Type	Description	Example
`length`	number	Length overall in feet	42
`beam`	number	Beam width in feet	13.5
`draft`	number	Draft in feet	2.8
`cabins`	number	Number of cabins	2
`heads`	number	Number of heads/bathrooms	1
`capacity`	number	Passenger capacity	12
`topSpeed`	number	Maximum speed in knots	48
`cruiseSpeed`	number	Cruising speed in knots	35
`fuelCapacity`	number	Fuel tank capacity in gallons	550
`waterCapacity`	number	Fresh water capacity in gallons	80

Engine Configuration

Field	Type	Description	Valid Values
`engineType`	string	Primary engine propulsion type	"Outboard", "Inboard", "Sterndrive", "Jet"
`engineCount`	number	Number of engines (1-6)	3

Individual Engine Details (1-6)

For each engine (engine1*, engine2*, engine3*, etc.), you can specify:

Field Pattern	Type	Description	Example
`engine1Type`	string	Engine propulsion type	"Outboard"
`engine1Make`	string	Engine manufacturer	"Yamaha"
`engine1Model`	string	Engine model	"F425 XTO"
`engine1Power`	number	Horsepower rating	425
`engine1Fuel`	string	Fuel type	"Gas", "Diesel"
`engine1Hours`	number	Total engine hours	250
`engine1Year`	number	Year of manufacture	2020
`engine1Condition`	string	Engine condition	"Excellent", "Good", "Fair"

Note: Replace "1" with 2-6 for additional engines (e.g., engine2Make, engine3Model, engine4Power, etc.)

Media & Content

Field	Type	Description	Example
`description`	string	Detailed boat description (supports HTML)	"<p>Pristine condition...</p>"
`photos`	string[]	Array of photo URLs	["https://...jpg", "https://...jpg"]
`featuredPhoto`	string	URL of primary/hero photo	"https://example.com/hero.jpg"

Voyage Photography

Field	Type	Description	Valid Values
`voyagePhotographyRequested`	boolean	Whether professional photography was requested	true, false
`voyagePackage`	string	Selected Voyage photography tier	"standard", "premium", "elite"

Minimal Example Request (Required Fields Only)

JSON

{
  "brokerId": "abc123def456",
  "brokerageId": "brkg_xyz789",
  "condition": "used",
  "year": 2020,
  "manufacturer": "Yellowfin",
  "model": "42 Offshore",
  "type": "Center Console",
  "price": 725000,
  "locationCity": "Miami",
  "locationState": "FL",
  "length": 42,
  "engineType": "Outboard",
  "engineCount": 3,
  "description": "Pristine offshore center console"
}

Comprehensive Example Request (With All Engine Details)

JSON

{
  "brokerId": "abc123def456",
  "brokerageId": "brkg_xyz789",
  "listingStatus": "active",
  "listingType": "premium",
  "condition": "used",
  "year": 2020,
  "manufacturer": "Yellowfin",
  "model": "42 Offshore",
  "type": "Center Console",
  "price": 725000,
  "contactForPrice": false,
  "hasReserve": false,
  "locationCity": "Miami",
  "locationState": "FL",
  "locationZIP": "33139",
  "length": 42,
  "beam": 13.5,
  "draft": 2.8,
  "cabins": 1,
  "heads": 1,
  "capacity": 12,
  "topSpeed": 48,
  "cruiseSpeed": 35,
  "fuelCapacity": 550,
  "waterCapacity": 80,
  "engineType": "Outboard",
  "engineCount": 3,
  "engine1Type": "Outboard",
  "engine1Make": "Yamaha",
  "engine1Model": "F425 XTO",
  "engine1Power": 425,
  "engine1Fuel": "Gas",
  "engine1Hours": 250,
  "engine1Year": 2020,
  "engine1Condition": "Excellent",
  "engine2Type": "Outboard",
  "engine2Make": "Yamaha",
  "engine2Model": "F425 XTO",
  "engine2Power": 425,
  "engine2Fuel": "Gas",
  "engine2Hours": 250,
  "engine2Year": 2020,
  "engine2Condition": "Excellent",
  "engine3Type": "Outboard",
  "engine3Make": "Yamaha",
  "engine3Model": "F425 XTO",
  "engine3Power": 425,
  "engine3Fuel": "Gas",
  "engine3Hours": 250,
  "engine3Year": 2020,
  "engine3Condition": "Excellent",
  "description": "<p>This pristine 2020 Yellowfin 42 Offshore represents the pinnacle of center console excellence...</p>",
  "photos": [
    "https://example.com/photo1.jpg",
    "https://example.com/photo2.jpg",
    "https://example.com/photo3.jpg"
  ],
  "featuredPhoto": "https://example.com/hero.jpg",
  "voyagePhotographyRequested": true,
  "voyagePackage": "premium"
}

cURL Example

cURL

curl -X POST https://us-central1-sportfishtrader-v5.cloudfunctions.net/createListingApi \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "brokerId": "abc123def456",
    "brokerageId": "brkg_xyz789",
    "condition": "used",
    "year": 2020,
    "manufacturer": "Yellowfin",
    "model": "42 Offshore",
    "type": "Center Console",
    "price": 725000,
    "locationCity": "Miami",
    "locationState": "FL",
    "length": 42,
    "engineType": "Outboard",
    "engineCount": 3,
    "description": "Pristine offshore center console"
  }'

Success Response

201 Created

{
  "id": "abc123xyz789",
  "message": "Listing created successfully"
}

Error Responses

400 Bad Request - Missing Required Field

{
  "error": "Missing required field: manufacturer"
}

403 Forbidden - Brokerage Mismatch

{
  "error": "brokerageId mismatch: API key belongs to a different brokerage"
}

401 Unauthorized - Invalid API Key

{
  "error": "Invalid or missing API key"
}

PUT

Update Listing

/updateListingApi/:listingId

Update an existing boat listing. You can only update listings that belong to your brokerage.

Path Parameters

Parameter	Type	Description
`listingId`	string	The unique ID of the listing to update

Example Request

cURL

curl -X PUT https://us-central1-sportfishtrader-v5.cloudfunctions.net/updateListingApi/abc123xyz789 \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 699000,
    "description": "Price reduced! Pristine condition, fully equipped for offshore fishing"
  }'

Response

200 OK

{
  "id": "abc123xyz789"
}

PATCH

Mark as Sold

/markAsSoldApi/:listingId

Mark a listing as sold and remove it from active listings.

Path Parameters

Parameter	Type	Description
`listingId`	string	The unique ID of the listing to mark as sold

Example Request

cURL

curl -X PATCH https://us-central1-sportfishtrader-v5.cloudfunctions.net/markAsSoldApi/abc123xyz789 \
  -H "x-api-key: your_api_key_here"

Response

200 OK

{
  "success": true,
  "message": "Listing marked as sold"
}

GET

Search Listings

/searchListingsApi

Retrieve listings that belong to your brokerage with optional filtering.

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status (active, sold, pending)
`limit`	number	Number of results to return (default: 50, max: 100)
`offset`	number	Pagination offset (default: 0)

Example Request

cURL

curl -X GET "https://us-central1-sportfishtrader-v5.cloudfunctions.net/searchListingsApi?status=active&limit=10" \
  -H "x-api-key: your_api_key_here"

Code Examples

JavaScript / Node.js

Using the Fetch API to create a listing:

JavaScript

const createListing = async (listingData) => {
  try {
    const response = await fetch(
      'https://us-central1-sportfishtrader-v5.cloudfunctions.net/createListingApi',
      {
        method: 'POST',
        headers: {
          'x-api-key': process.env.SPORTFISH_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(listingData)
      }
    );

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Listing created:', data.id);
    return data;
  } catch (error) {
    console.error('Error creating listing:', error);
    throw error;
  }
};

// Example usage
const newListing = {
  title: '2020 Yellowfin 42 Offshore',
  price: 725000,
  year: 2020,
  make: 'Yellowfin',
  model: '42 Offshore',
  length: 42,
  location: 'Miami, FL',
  description: 'Pristine condition, fully equipped for offshore fishing',
  photoUrls: [
    'https://example.com/photo1.jpg',
    'https://example.com/photo2.jpg'
  ]
};

createListing(newListing);

Python

Using the requests library:

Python

import requests
import os
import json

def create_listing(listing_data):
    url = 'https://us-central1-sportfishtrader-v5.cloudfunctions.net/createListingApi'
    headers = {
        'x-api-key': os.environ.get('SPORTFISH_API_KEY'),
        'Content-Type': 'application/json'
    }
    
    try:
        response = requests.post(url, headers=headers, json=listing_data)
        response.raise_for_status()
        
        data = response.json()
        print(f'Listing created: {data["id"]}')
        return data
    except requests.exceptions.RequestException as e:
        print(f'Error creating listing: {e}')
        raise

# Example usage
new_listing = {
    'title': '2020 Yellowfin 42 Offshore',
    'price': 725000,
    'year': 2020,
    'make': 'Yellowfin',
    'model': '42 Offshore',
    'length': 42,
    'location': 'Miami, FL',
    'description': 'Pristine condition, fully equipped for offshore fishing',
    'photoUrls': [
        'https://example.com/photo1.jpg',
        'https://example.com/photo2.jpg'
    ]
}

create_listing(new_listing)

PHP

Using cURL in PHP:

PHP

<?php
function createListing($listingData) {
    $url = 'https://us-central1-sportfishtrader-v5.cloudfunctions.net/createListingApi';
    $apiKey = getenv('SPORTFISH_API_KEY');
    
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($listingData));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'x-api-key: ' . $apiKey,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode !== 201) {
        throw new Exception("HTTP error! status: $httpCode");
    }
    
    $data = json_decode($response, true);
    echo "Listing created: " . $data['id'] . "\n";
    return $data;
}

// Example usage
$newListing = [
    'title' => '2020 Yellowfin 42 Offshore',
    'price' => 725000,
    'year' => 2020,
    'make' => 'Yellowfin',
    'model' => '42 Offshore',
    'length' => 42,
    'location' => 'Miami, FL',
    'description' => 'Pristine condition, fully equipped for offshore fishing',
    'photoUrls' => [
        'https://example.com/photo1.jpg',
        'https://example.com/photo2.jpg'
    ]
];

createListing($newListing);
?>

Troubleshooting

Common Errors

401 Unauthorized

Cause: Invalid or missing API key

Solution:

Verify your API key is correct
Ensure you're using the x-api-key header
Check that your API key hasn't expired or been revoked

400 Bad Request

Cause: Missing required fields or invalid data format

Solution:

Check that all required fields are included
Verify data types match the API specification
Ensure JSON is properly formatted

404 Not Found

Cause: Listing doesn't exist or doesn't belong to your brokerage

Solution:

Verify the listing ID is correct
Ensure the listing belongs to your brokerage
Check that the listing hasn't been deleted

405 Method Not Allowed

Cause: Using wrong HTTP method for the endpoint

Solution:

Use POST for creating listings
Use PUT for updating listings
Use PATCH for marking as sold
Use GET for searching listings

500 Internal Server Error

Cause: Server-side error

Solution:

Retry the request after a short delay
Check the status page for service issues
Contact support if the issue persists

Rate Limits

To ensure fair usage and platform stability, the following rate limits apply:

Plan	Requests per Minute	Requests per Hour
Individual	30	1,000
Brokerage	100	5,000
Enterprise	Custom	Custom

Rate Limit Headers

Each API response includes rate limit information in the headers:

X-RateLimit-Limit: Your rate limit ceiling
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Time when the rate limit resets (Unix timestamp)

Getting Help

If you need assistance with the API, we're here to help:

Documentation

Review this documentation thoroughly for answers to common questions.

Status Page

Check our status page for any ongoing service issues.

Contact Support

Reach out via the contact page for technical assistance.

When Contacting Support

Please include the following information:

Your API key (first 8 characters only)
Endpoint you're trying to use
Complete error message and HTTP status code
Sample request (with sensitive data removed)
Timestamp of the error