API Reference

Chat Completions

Create chat completions with the Yachtsy Agent model for sailing expertise.

Overview

The chat completions endpoint is the primary way to interact with Yachtsy Agent. It follows the OpenAI Chat Completions API format exactly, making it a drop-in replacement.

Endpoint

POST /v1/chat/completions

Request Format

{
  "model": "yachtsy-deep-research-agent",
  "messages": [
    {"role": "system", "content": "You are a sailing expert."},
    {"role": "user", "content": "What's the difference between a sloop and a ketch?"}
  ],
  "stream": true,
  "temperature": 0.7,
  "max_tokens": 1000
}

Parameters

Parameter	Type	Required	Default	Description
`model`	string	Yes	-	One of: `"yachtsy-agent"`, `"yachtsy-deep-research-agent"`, `"yachtsy-listings-agent"`, `"yachtsy-survey-agent"`
`messages`	array	Yes	-	Array of message objects
`stream`	boolean	No	`false`	Enable streaming responses
`temperature`	number	No	`0.7`	Randomness (0.0-2.0)
`max_tokens`	number	No	`1000`	Maximum response length
`top_p`	number	No	`1.0`	Nucleus sampling
`frequency_penalty`	number	No	`0.0`	Frequency penalty (-2.0 to 2.0)
`presence_penalty`	number	No	`0.0`	Presence penalty (-2.0 to 2.0)
`stop`	string/array	No	`null`	Stop sequences

Message Format

Each message object contains:

{
  "role": "user|assistant|system",
  "content": "The message content"
}

Roles:

system - Sets the behavior/context for the assistant
user - Messages from the user
assistant - Previous responses from the assistant

Response Format

Non-Streaming Response

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "yachtsy-agent",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A sloop has one mast with a mainsail and jib, while a ketch has two masts..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  },
  "system_fingerprint": "fp_44709d6fcb"
}

Streaming Response

When stream: true, responses are sent as Server-Sent Events:

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"yachtsy-agent","choices":[{"index":0,"delta":{"role":"assistant","content":"A"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"yachtsy-agent","choices":[{"index":0,"delta":{"content":" sloop"},"finish_reason":null}]}

data: [DONE]

Code Examples

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.yachtsy.ai/v1",
    api_key="your-api-key"
)

# Deep Research Analysis
response = client.chat.completions.create(
    model="yachtsy-deep-research-agent",
    messages=[
        {"role": "user", "content": "Comprehensive analysis of Catalina 34 market positioning"}
    ],
    stream=True,
    max_tokens=4000
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

# Boat Listings Search
response = client.chat.completions.create(
    model="yachtsy-listings-agent",
    messages=[
        {"role": "user", "content": "Find Beneteau 40 boats under $200k in Florida"}
    ],
    stream=True
)

# Boat Survey Analysis
response = client.chat.completions.create(
    model="yachtsy-survey-agent",
    messages=[
        {"role": "user", "content": "Survey this Catalina 34: https://sailboatlistings.com/view/123456"}
    ],
    stream=True
)

# General Sailing Questions
response = client.chat.completions.create(
    model="yachtsy-agent",
    messages=[
        {"role": "user", "content": "How do I reef a mainsail in heavy weather?"}
    ],
    stream=True
)

JavaScript/TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.yachtsy.ai/v1',
  apiKey: process.env.YACHTSY_API_KEY
});

// Deep Research Analysis (with streaming)
const researchStream = await client.chat.completions.create({
  model: 'yachtsy-deep-research-agent',
  messages: [
    { role: 'user', content: 'Market analysis of Bavaria vs Jeanneau cruising yachts' }
  ],
  stream: true,
  max_tokens: 4000
});

for await (const chunk of researchStream) {
  if (chunk.choices[0]?.delta?.content) {
    process.stdout.write(chunk.choices[0].delta.content);
  }
}

// Boat Listings Search
const listingsResponse = await client.chat.completions.create({
  model: 'yachtsy-listings-agent',
  messages: [
    { role: 'user', content: 'Hunter 40 boats in the Pacific Northwest under $150k' }
  ],
  stream: true
});

// Boat Survey Analysis
const surveyResponse = await client.chat.completions.create({
  model: 'yachtsy-survey-agent', 
  messages: [
    { role: 'user', content: 'Analyze this boat for potential issues and condition' }
  ],
  stream: true
});

// General Sailing Assistant
const generalResponse = await client.chat.completions.create({
  model: 'yachtsy-agent',
  messages: [
    { role: 'user', content: 'How do I choose the right anchor for my boat?' }
  ],
  temperature: 0.7
});

cURL

# Deep Research Analysis
curl -N -X POST https://api.yachtsy.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "yachtsy-deep-research-agent",
    "messages": [
      {"role": "user", "content": "Comprehensive analysis of Catalina 34 vs Hunter 34"}
    ],
    "stream": true,
    "max_tokens": 4000
  }'

# Boat Listings Search
curl -N -X POST https://api.yachtsy.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "yachtsy-listings-agent",
    "messages": [
      {"role": "user", "content": "Catalina 34 boats under $50k"}
    ],
    "stream": true
  }'

# Boat Survey Analysis  
curl -N -X POST https://api.yachtsy.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "yachtsy-survey-agent",
    "messages": [
      {"role": "user", "content": "Survey this boat listing for potential issues"}
    ],
    "stream": true
  }'

# General Sailing Questions
curl -X POST https://api.yachtsy.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "yachtsy-agent",
    "messages": [
      {"role": "user", "content": "What is the best wind angle for sailing upwind?"}
    ],
    "temperature": 0.7,
    "max_tokens": 300
  }'

Best Practices

System Messages

Use system messages to set context for sailing-specific queries:

{
  "role": "system",
  "content": "You are an experienced sailing instructor and yacht broker. Provide practical, safety-focused advice for recreational sailors."
}

Temperature Settings

0.0-0.3: Factual information (specifications, regulations)
0.4-0.7: Balanced responses (recommendations, explanations)
0.8-1.0: Creative suggestions (trip planning, problem-solving)

Streaming for Long Responses

Enable streaming for complex topics that generate longer responses:

{
  "stream": true,
  "max_tokens": 1500
}

Common Sailing Queries

Yachtsy Agent excels at these types of sailing-related questions:

Boat Selection: "What's the best 40ft bluewater cruiser?"
Technical: "How do I troubleshoot my furling system?"
Navigation: "What's the best route from Florida to the Bahamas?"
Weather: "How do I read a weather routing chart?"
Maintenance: "How often should I service my winches?"
Safety: "What safety equipment do I need for offshore sailing?"

Pro Tip: Include specific details about your boat, experience level, and sailing conditions for more targeted advice.

Responses

Understanding API response formats, status codes, and error handling for Yachtsy Agent.

Models

Complete guide to all available Yachtsy AI models and their specialized capabilities.