API Reference

Overview

Yachtsy Agent provides an OpenAI-compatible API with specialized sailing knowledge. All endpoints follow OpenAI's API conventions for seamless integration with existing tools and SDKs.

Quick Start

# Get your API key first
curl -X POST http://localhost:8000/admin/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name": "My App Key"}'

# Use the API
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "yachtsy-agent",
    "messages": [{"role": "user", "content": "Explain different sail types"}]
  }'

Available Endpoints

Chat Completions

• POST /v1/chat/completions - Main chat endpoint with streaming support
• GET /v1/models - List available models
• GET /v1/models/{model_id} - Get model information

Legacy Compatibility

• POST /v1/completions - Legacy text completion endpoint
• POST /v1/completion - Alternative legacy endpoint

Management

• POST /admin/api-keys - Create API keys (development only)

Authentication

All API requests require authentication using a Bearer token:

Authorization: Bearer your-api-key-here

Getting an API Key

Development Environment:

curl -X POST http://localhost:8000/admin/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name": "Development Key"}'

Production: Get your API key from the web interface: User Menu → API Keys

Models

Available specialized models:

Model Selection Guide

For comprehensive research and analysis:

• Use yachtsy-deep-research-agent for market studies, competitive analysis, and detailed investigations

For finding boats:

• Use yachtsy-listings-agent for searching current boat inventory and listings

For boat inspections:

• Use yachtsy-survey-agent for condition assessments, survey reports, and inspection analysis

For general sailing questions:

• Use yachtsy-agent for conversational assistance and general sailing advice

Error Handling

The API returns standard HTTP status codes and JSON error responses:

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Common error codes:

• 400 - Bad Request (malformed request)
• 401 - Unauthorized (invalid API key)
• 429 - Rate Limited
• 500 - Internal Server Error

Rate Limits

Development environment has generous rate limits. Production limits depend on your subscription plan.