API Documentation

Complete guide to integrating deep navy with your development workflow.

📚 Table of Contents

• Quick Start
  • 1. Get Your API Key
  • 2. Configure Xcode 26
  • 3. Test Your Connection
• Base URL
• Authentication
  • Security Best Practices
• Rate Limits
  • Rate Limit Headers
• Available Models
  • List Available Models
  • Model Capabilities
• Chat Completions
  • Create Chat Completion
  • Streaming Responses
• Request Parameters
  • Required Parameters
  • Optional Parameters
  • Message Object
• Error Handling
  • HTTP Status Codes
  • Error Response Format
  • Common Errors
• Code Examples
  • Swift (iOS/macOS)
  • Node.js
  • Python
  • cURL Examples
• Best Practices
  • Performance Optimization
  • Security Guidelines
  • Error Handling
  • Prompt Engineering
• SDKs and Libraries
  • Official SDKs
  • Community Libraries
• Webhooks (Enterprise)
• Support
  • Getting Help
  • Response Times

Quick Start

1. Get Your API Key

1. Sign in with Apple
2. Go to your Dashboard
3. Click “Create New Key”
4. Copy your API key (you won’t see it again!)

2. Configure Xcode 26

1. Open Xcode → Preferences → Intelligence Mode
2. Set Base URL: https://api.deepnavy.ai
3. Enter your API key
4. Enable Intelligence Mode

3. Test Your Connection

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.deepnavy.ai/v1/models

Base URL

https://api.deepnavy.ai

Authentication

All API requests require authentication using Bearer tokens:

Authorization: Bearer YOUR_API_KEY

Security Best Practices

• Never expose API keys in client-side code
• Use environment variables in your applications
• Regenerate keys if compromised
• Monitor usage in your dashboard

Rate Limits

Rate limits vary by subscription plan:

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Available Models

List Available Models

GET /v1/models

Response:

{
  "object": "list",
  "data": [
    {
      "id": "claude-3-5-sonnet-20241022",
      "object": "model",
      "created": 1703980800,
      "owned_by": "anthropic",
      "capabilities": {
        "code_generation": true,
        "code_analysis": true,
        "documentation": true,
        "debugging": true
      },
      "context_window": 200000,
      "max_output_tokens": 8192
    },
    {
      "id": "claude-3-haiku-20240307",
      "object": "model",
      "created": 1703980800,
      "owned_by": "anthropic",
      "capabilities": {
        "code_generation": true,
        "quick_responses": true,
        "debugging": true
      },
      "context_window": 200000,
      "max_output_tokens": 4096
    }
  ]
}

Model Capabilities

Claude 3.5 Sonnet

• Best for: Complex coding tasks, architecture decisions, code reviews
• Context Window: 200,000 tokens
• Strengths: Advanced reasoning, multi-language support, detailed explanations

Claude 3 Haiku

• Best for: Quick fixes, simple queries, real-time assistance
• Context Window: 200,000 tokens
• Strengths: Fast responses, efficient for simple tasks

Claude 3 Opus

• Best for: Most complex problems, large codebases, critical decisions
• Context Window: 200,000 tokens
• Strengths: Highest capability model, best for challenging tasks

Chat Completions

Create Chat Completion

POST /v1/chat/completions
Content-Type: application/json

Request Body:

{
  "model": "claude-3-5-sonnet-20241022",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant for iOS development."
    },
    {
      "role": "user",
      "content": "Help me implement a SwiftUI view for a user profile screen."
    }
  ],
  "max_tokens": 2048,
  "temperature": 0.7,
  "stream": false
}

Response:

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "claude-3-5-sonnet-20241022",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I'll help you create a SwiftUI user profile view. Here's a comprehensive implementation:\n\n```swift\nstruct UserProfileView: View {\n    @State private var user: User\n    \n    var body: some View {\n        NavigationView {\n            ScrollView {\n                VStack(alignment: .leading, spacing: 20) {\n                    // Profile Header\n                    profileHeader\n                    \n                    // Profile Details\n                    profileDetails\n                    \n                    // Action Buttons\n                    actionButtons\n                }\n                .padding()\n            }\n            .navigationTitle(\"Profile\")\n            .navigationBarTitleDisplayMode(.large)\n        }\n    }\n}\n```\n\nThis creates a clean, native SwiftUI profile screen with proper navigation and scrolling."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 56,
    "completion_tokens": 168,
    "total_tokens": 224
  }
}

Streaming Responses

For real-time responses (recommended for Xcode 26):

{
  "model": "claude-3-5-sonnet-20241022",
  "messages": [...],
  "stream": true
}

Streaming Response:

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"claude-3-5-sonnet-20241022","choices":[{"index":0,"delta":{"role":"assistant","content":"I'll"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"claude-3-5-sonnet-20241022","choices":[{"index":0,"delta":{"content":" help"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"claude-3-5-sonnet-20241022","choices":[{"index":0,"delta":{"content":" you"},"finish_reason":null}]}

data: [DONE]

Request Parameters

Required Parameters

• model (string): The model ID to use
• messages (array): List of message objects

Optional Parameters

• max_tokens (integer): Maximum tokens to generate (default: 2048)
• temperature (float): Randomness (0.0-2.0, default: 1.0)
• stream (boolean): Enable streaming responses (default: false)
• top_p (float): Nucleus sampling (0.0-1.0, default: 1.0)
• stop (string/array): Stop sequences

Message Object

{
  "role": "user|assistant|system",
  "content": "Message content here"
}

Error Handling

HTTP Status Codes

• 200 - Success
• 400 - Bad Request (invalid parameters)
• 401 - Unauthorized (invalid API key)
• 403 - Forbidden (rate limit exceeded)
• 429 - Too Many Requests (rate limited)
• 500 - Internal Server Error
• 503 - Service Unavailable (maintenance)

Error Response Format

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "Missing required parameter: model",
    "param": "model"
  }
}

Common Errors

Invalid API Key

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

Rate Limit Exceeded

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please wait before making more requests."
  }
}

Model Not Found

{
  "error": {
    "type": "invalid_request_error",
    "code": "model_not_found",
    "message": "The model 'invalid-model' does not exist"
  }
}

Code Examples

Swift (iOS/macOS)

import Foundation

struct AIClient {
    private let apiKey: String
    private let baseURL = "https://api.deepnavy.ai"

    init(apiKey: String) {
        self.apiKey = apiKey
    }

    func chatCompletion(messages: [Message]) async throws -> ChatResponse {
        let url = URL(string: "\(baseURL)/v1/chat/completions")!
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")

        let body = ChatRequest(
            model: "claude-3-5-sonnet-20241022",
            messages: messages,
            maxTokens: 2048
        )

        request.httpBody = try JSONEncoder().encode(body)

        let (data, response) = try await URLSession.shared.data(for: request)

        guard let httpResponse = response as? HTTPURLResponse,
              httpResponse.statusCode == 200 else {
            throw AIError.requestFailed
        }

        return try JSONDecoder().decode(ChatResponse.self, from: data)
    }
}

Node.js

const fetch = require('node-fetch');

class AIClient {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.baseURL = 'https://api.deepnavy.ai';
    }

    async chatCompletion(messages) {
        const response = await fetch(`${this.baseURL}/v1/chat/completions`, {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${this.apiKey}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                model: 'claude-3-5-sonnet-20241022',
                messages: messages,
                max_tokens: 2048
            })
        });

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

        return await response.json();
    }
}

// Usage
const client = new AIClient(process.env.AI_API_KEY);
const response = await client.chatCompletion([
    { role: 'user', content: 'Write a Swift function to validate email addresses' }
]);

Python

import requests
import json

class AIClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.deepnavy.ai"

    def chat_completion(self, messages):
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

        data = {
            "model": "claude-3-5-sonnet-20241022",
            "messages": messages,
            "max_tokens": 2048
        }

        response = requests.post(
            f"{self.base_url}/v1/chat/completions",
            headers=headers,
            json=data
        )

        response.raise_for_status()
        return response.json()

# Usage
client = AIClient(os.getenv("AI_API_KEY"))
response = client.chat_completion([
    {"role": "user", "content": "Help me optimize this Swift code for performance"}
])

cURL Examples

List Models

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.deepnavy.ai/v1/models

Chat Completion

curl -X POST https://api.deepnavy.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
      {
        "role": "user",
        "content": "Write a SwiftUI view for a login screen"
      }
    ],
    "max_tokens": 2048
  }'

Streaming Request

curl -X POST https://api.deepnavy.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [{"role": "user", "content": "Explain Swift optionals"}],
    "stream": true
  }'

Best Practices

Performance Optimization

1. Use Streaming - Enable streaming for real-time responses
2. Choose Right Model - Use Haiku for simple tasks, Sonnet for complex ones
3. Optimize Prompts - Be specific and provide context
4. Cache Responses - Cache common responses locally

Security Guidelines

1. Server-Side Keys - Never expose API keys in client apps
2. Environment Variables - Store keys in secure environment variables
3. Key Rotation - Regenerate keys periodically
4. Monitor Usage - Watch for unusual activity patterns

Error Handling

1. Retry Logic - Implement exponential backoff for rate limits
2. Fallback Models - Have backup model options
3. Graceful Degradation - Handle API unavailability
4. User Feedback - Provide clear error messages to users

Prompt Engineering

1. Be Specific - Provide clear, detailed instructions
2. Include Context - Share relevant code and requirements
3. Set Expectations - Specify desired output format
4. Iterate - Refine prompts based on responses

SDKs and Libraries

Official SDKs

• Swift Package - Coming soon
• CocoaPods - Coming soon
• npm Package - Coming soon

Community Libraries

• OpenAI-compatible libraries work out of the box
• Most HTTP clients support our REST API
• WebSocket support for streaming (coming soon)

Webhooks (Enterprise)

Enterprise customers can configure webhooks for:

• Usage alerts and notifications
• Bill payment confirmations
• Security events and alerts
• Service status updates

Contact support@deepnavy.ai for webhook setup.

Support

Getting Help

• Technical Support: support@deepnavy.ai
• Documentation: Use the Support page

Response Times

• Starter Plan: 24 hours
• Professional Plan: 12 hours
• Enterprise Plan: 4 hours

API Version: v1 Last Updated: December 1, 2024

For the most up-to-date API documentation and examples, visit our Developer Portal.