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
| Endpoint | Method | Purpose |
|---|---|---|
/v1/chat/completions | POST | Main chat interface |
/v1/models | GET | List available models |
/v1/models/{id} | GET | Get model details |
/v1/completions | POST | Legacy text completion |
/admin/api-keys | POST | Create API key (dev only) |
Authentication
# Headers required for all requests
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Model Information
| Model ID | Context Length | Best For |
|---|---|---|
yachtsy-agent | 4096 tokens | General sailing questions, conversational assistance |
yachtsy-deep-research-agent | 4096 tokens | Research analysis, market studies, comparisons |
yachtsy-listings-agent | 4096 tokens | Boat search, inventory queries, listings |
yachtsy-survey-agent | 4096 tokens | Boat 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
| Parameter | Type | Default | Description |
|---|---|---|---|
model | string | required | Must be "yachtsy-agent" |
messages | array | required | Conversation messages |
stream | boolean | false | Enable streaming |
temperature | number | 0.7 | Randomness (0.0-2.0) |
max_tokens | number | 1000 | Max response length |
top_p | number | 1.0 | Nucleus sampling |
frequency_penalty | number | 0.0 | Frequency penalty |
presence_penalty | number | 0.0 | Presence penalty |
stop | string/array | null | Stop sequences |
Error Codes
| Code | Meaning | Solution |
|---|---|---|
| 400 | Bad Request | Check request format |
| 401 | Unauthorized | Verify API key |
| 429 | Rate Limited | Wait and retry |
| 500 | Server Error | Try 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"
Navigation & Weather
"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
| Temperature | Use Case | Example |
|---|---|---|
| 0.0-0.3 | Factual information | Specifications, regulations |
| 0.4-0.7 | Balanced advice | Boat recommendations |
| 0.8-1.0 | Creative suggestions | Trip 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
| Environment | Base URL | Purpose |
|---|---|---|
| Development | http://localhost:8000/v1 | Local testing |
| Staging | https://staging-api.yachtsy.com/v1 | Pre-production |
| Production | https://api.yachtsy.com/v1 | Live applications |
Bookmark this page for quick access to essential Yachtsy Agent information while developing your sailing applications!