Quick Reference

Quick reference guide for Yachtsy Agent API endpoints, parameters, and common use cases.

Quick Reference

Essential information for working with Yachtsy Agent API at a glance.

API Endpoints

EndpointMethodPurpose
/v1/chat/completionsPOSTMain chat interface
/v1/modelsGETList available models
/v1/models/{id}GETGet model details
/v1/completionsPOSTLegacy text completion
/admin/api-keysPOSTCreate API key (dev only)

Authentication

# Headers required for all requests
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Model Information

Model IDContext LengthBest For
yachtsy-agent4096 tokensGeneral sailing questions, conversational assistance
yachtsy-deep-research-agent4096 tokensResearch analysis, market studies, comparisons
yachtsy-listings-agent4096 tokensBoat search, inventory queries, listings
yachtsy-survey-agent4096 tokensBoat inspections, condition assessment, surveys

Common Request Examples

Basic Chat Completion

{
  "model": "yachtsy-agent",
  "messages": [
    {"role": "user", "content": "What's the best 35ft cruising sailboat?"}
  ]
}

With System Context

{
  "model": "yachtsy-agent",
  "messages": [
    {"role": "system", "content": "You are helping a novice sailor choose their first boat."},
    {"role": "user", "content": "What should I look for in a beginner-friendly sailboat?"}
  ],
  "temperature": 0.7
}

Streaming Request

{
  "model": "yachtsy-agent",
  "messages": [
    {"role": "user", "content": "Explain how to reef a mainsail step by step"}
  ],
  "stream": true
}

Response Format

Non-Streaming Response

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "yachtsy-agent",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "For a 35ft cruising sailboat, I'd recommend..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 250,
    "total_tokens": 265
  }
}

Streaming Response

data: {"id":"chatcmpl-123","choices":[{"delta":{"content":"For"}}]}

data: {"id":"chatcmpl-123","choices":[{"delta":{"content":" a"}}]}

data: [DONE]

Parameters Reference

ParameterTypeDefaultDescription
modelstringrequiredMust be "yachtsy-agent"
messagesarrayrequiredConversation messages
streambooleanfalseEnable streaming
temperaturenumber0.7Randomness (0.0-2.0)
max_tokensnumber1000Max response length
top_pnumber1.0Nucleus sampling
frequency_penaltynumber0.0Frequency penalty
presence_penaltynumber0.0Presence penalty
stopstring/arraynullStop sequences

Error Codes

CodeMeaningSolution
400Bad RequestCheck request format
401UnauthorizedVerify API key
429Rate LimitedWait and retry
500Server ErrorTry again later

SDK Quick Start

Python (OpenAI)

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="your-key"
)

response = client.chat.completions.create(
    model="yachtsy-agent",
    messages=[{"role": "user", "content": "sailing question"}]
)

JavaScript/Node.js

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:8000/v1',
  apiKey: 'your-key'
});

const response = await client.chat.completions.create({
  model: 'yachtsy-agent',
  messages: [{ role: 'user', content: 'sailing question' }]
});

cURL

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "yachtsy-agent",
    "messages": [{"role": "user", "content": "sailing question"}]
  }'

Best Practices Checklist

✅ Do's

  • Use specific sailing terminology for better responses
  • Include boat details when asking for recommendations
  • Set appropriate temperature (0.3 for facts, 0.7 for advice)
  • Implement proper error handling
  • Use streaming for long responses
  • Keep API keys secure (backend only)

❌ Don'ts

  • Don't expose API keys in frontend code
  • Don't skip input validation
  • Don't ignore rate limits
  • Don't use generic prompts for specific sailing questions
  • Don't forget to handle network errors

Common Sailing Query Patterns

Boat Selection

"Best [size] [type] for [use case] under $[budget]"
Example: "Best 40ft catamaran for coastal cruising under $200k"

Technical Questions

"How to [action] [equipment] in [conditions]"
Example: "How to reef mainsail in 25 knot winds"
"Route from [departure] to [destination] in [season]"
Example: "Route from Florida to Bahamas in December"

Equipment Recommendations

"What [equipment] for [boat type] doing [activity]"
Example: "What autopilot for 35ft sloop doing offshore passages"

Temperature Guidelines

TemperatureUse CaseExample
0.0-0.3Factual informationSpecifications, regulations
0.4-0.7Balanced adviceBoat recommendations
0.8-1.0Creative suggestionsTrip planning, problem solving

Token Estimation

Rough token counts for planning:

  • Average word ≈ 1.3 tokens
  • Typical question: 10-50 tokens
  • Detailed response: 200-800 tokens
  • Maximum context: 4096 tokens

Environment URLs

EnvironmentBase URLPurpose
Developmenthttp://localhost:8000/v1Local testing
Staginghttps://staging-api.yachtsy.com/v1Pre-production
Productionhttps://api.yachtsy.com/v1Live applications
Bookmark this page for quick access to essential Yachtsy Agent information while developing your sailing applications!