> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costa.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Integrations

> Connect Costa to any AI agent using our OpenAI-compatible API

## Universal API Integration

Costa provides an OpenAI-compatible API that works with virtually any AI agent, custom application, or automation tool. This allows you to integrate enterprise-grade AI capabilities into your existing workflows while maintaining the highest security standards.

## API Configuration

### Base Configuration

<CodeGroup>
  ```bash Environment Variables theme={null}
  export COSTA_API_KEY="REPLACE_WITH_YOUR_COSTA_API_KEY"
  export COSTA_BASE_URL="https://ai.costa.app/api/v1"
  export COSTA_MODEL="costa/auto"
  ```

  ```yaml Configuration File theme={null}
  api:
    provider: costa-code
    base_url: https://ai.costa.app/api/v1
    api_key: costa_ent_your_key_here
    
  models:
    coding: costa/enterprise-coder-v1
    reasoning: costa/secure-claude-3-5-sonnet
    compliance: costa/compliance-assistant
    
  security:
    level: high
    data_residency: us-east
    audit_enabled: true
    zero_retention: false
  ```

  ```json JSON Configuration theme={null}
  {
    "api": {
      "provider": "costa-code",
      "baseUrl": "https://ai.costa.app/api/v1",
      "apiKey": "costa_ent_your_key_here"
    },
    "security": {
      "level": "high",
      "dataResidency": "us-east",
      "auditEnabled": true,
      "zeroRetention": false
    }
  }
  ```
</CodeGroup>

## Integration Examples

### Python SDK Integration

<CodeGroup>
  ```python OpenAI Python SDK theme={null}
  import openai

  # Configure Costa as OpenAI provider
  client = openai.OpenAI(
      api_key="costa_ent_your_key_here",
      base_url="https://ai.costa.app/api/v1"
  )

  # Basic chat completion
  response = client.chat.completions.create(
      model="costa/enterprise-coder-v1",
      messages=[
          {"role": "user", "content": "Write a secure Python function for user authentication"}
      ],
      max_tokens=1000,
      temperature=0.7
  )

  print(response.choices[0].message.content)

  # With enterprise security headers
  response = client.chat.completions.create(
      model="costa/secure-claude-3-5-sonnet",
      messages=[
          {"role": "user", "content": "Review this code for security vulnerabilities"}
      ],
      extra_headers={
          "Costa-Security-Level": "maximum",
          "Costa-Data-Residency": "us-east",
          "Costa-Audit-Enabled": "true",
          "Costa-Zero-Retention": "true"
      }
  )
  ```

  ```python Custom Python Integration theme={null}
  import requests
  import json

  class CostaCodeClient:
      def __init__(self, api_key, base_url="https://ai.costa.app/api/v1"):
          self.api_key = api_key
          self.base_url = base_url
          self.headers = {
              "Authorization": f"Bearer {api_key}",
              "Content-Type": "application/json"
          }
      
      def chat_completion(self, model, messages, **kwargs):
          """Send chat completion request to Costa"""
          url = f"{self.base_url}/chat/completions"
          
          payload = {
              "model": model,
              "messages": messages,
              **kwargs
          }
          
          response = requests.post(url, headers=self.headers, json=payload)
          response.raise_for_status()
          return response.json()
      
      def secure_completion(self, model, messages, security_level="high", **kwargs):
          """Send completion with enhanced security"""
          secure_headers = {
              **self.headers,
              "Costa-Security-Level": security_level,
              "Costa-Audit-Enabled": "true"
          }
          
          url = f"{self.base_url}/chat/completions"
          payload = {
              "model": model,
              "messages": messages,
              **kwargs
          }
          
          response = requests.post(url, headers=secure_headers, json=payload)
          response.raise_for_status()
          return response.json()

  # Usage example
  client = CostaCodeClient("costa_ent_your_key_here")

  response = client.secure_completion(
      model="costa/enterprise-coder-v1",
      messages=[{"role": "user", "content": "Generate a secure API endpoint"}],
      max_tokens=500,
      security_level="maximum"
  )
  ```
</CodeGroup>

### JavaScript/Node.js Integration

<CodeGroup>
  ```javascript OpenAI Node.js SDK theme={null}
  import OpenAI from 'openai';

  // Configure Costa client
  const openai = new OpenAI({
    apiKey: 'costa_ent_your_key_here',
    baseURL: 'https://ai.costa.app/api/v1'
  });

  // Basic completion
  async function generateCode(prompt) {
    const completion = await openai.chat.completions.create({
      model: 'costa/enterprise-coder-v1',
      messages: [{ role: 'user', content: prompt }],
      max_tokens: 1000,
      temperature: 0.7
    });
    
    return completion.choices[0].message.content;
  }

  // Enterprise security completion
  async function secureGeneration(prompt, securityLevel = 'high') {
    const completion = await openai.chat.completions.create({
      model: 'costa/secure-claude-3-5-sonnet',
      messages: [{ role: 'user', content: prompt }],
      max_tokens: 1500,
      extra_headers: {
        'Costa-Security-Level': securityLevel,
        'Costa-Audit-Enabled': 'true',
        'Costa-Data-Residency': 'us-east'
      }
    });
    
    return completion.choices[0].message.content;
  }

  // Usage
  const code = await generateCode('Create a REST API for user management');
  const secureCode = await secureGeneration('Review this payment processing code', 'maximum');
  ```

  ```javascript Custom Fetch Integration theme={null}
  class CostaCodeAPI {
    constructor(apiKey, baseURL = 'https://ai.costa.app/api/v1') {
      this.apiKey = apiKey;
      this.baseURL = baseURL;
    }

    async chatCompletion(model, messages, options = {}) {
      const response = await fetch(`${this.baseURL}/chat/completions`, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json',
          ...options.headers
        },
        body: JSON.stringify({
          model,
          messages,
          ...options.params
        })
      });

      if (!response.ok) {
        throw new Error(`API request failed: ${response.statusText}`);
      }

      return response.json();
    }

    async secureCompletion(model, messages, securityOptions = {}) {
      const headers = {
        'Costa-Security-Level': securityOptions.level || 'high',
        'Costa-Audit-Enabled': 'true',
        'Costa-Data-Residency': securityOptions.region || 'us-east'
      };

      if (securityOptions.zeroRetention) {
        headers['Costa-Zero-Retention'] = 'true';
      }

      return this.chatCompletion(model, messages, {
        headers,
        params: securityOptions.params || {}
      });
    }
  }

  // Usage
  const costa = new CostaCodeAPI('costa_ent_your_key_here');

  const result = await costa.secureCompletion(
    'costa/compliance-assistant',
    [{ role: 'user', content: 'Check this healthcare code for HIPAA compliance' }],
    {
      level: 'maximum',
      region: 'us-east',
      zeroRetention: true,
      params: { max_tokens: 2000 }
    }
  );
  ```
</CodeGroup>

### cURL Examples

<CodeGroup>
  ```bash Basic Chat Completion theme={null}
  curl -X POST "https://ai.costa.app/api/v1/chat/completions" \
    -H "Authorization: Bearer costa_ent_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "costa/enterprise-coder-v1",
      "messages": [
        {
          "role": "user",
          "content": "Write a secure authentication middleware for Express.js"
        }
      ],
      "max_tokens": 1000,
      "temperature": 0.7
    }'
  ```

  ```bash Enterprise Security Request theme={null}
  curl -X POST "https://ai.costa.app/api/v1/chat/completions" \
    -H "Authorization: Bearer costa_ent_your_key_here" \
    -H "Content-Type: application/json" \
    -H "Costa-Security-Level: maximum" \
    -H "Costa-Data-Residency: us-east" \
    -H "Costa-Audit-Enabled: true" \
    -H "Costa-Zero-Retention: true" \
    -d '{
      "model": "costa/secure-claude-3-5-sonnet",
      "messages": [
        {
          "role": "user",
          "content": "Review this financial transaction code for SOX compliance"
        }
      ],
      "max_tokens": 2000,
      "temperature": 0.3
    }'
  ```

  ```bash Compliance Check Request theme={null}
  curl -X POST "https://ai.costa.app/api/v1/chat/completions" \
    -H "Authorization: Bearer costa_ent_your_key_here" \
    -H "Content-Type: application/json" \
    -H "Costa-Security-Level: maximum" \
    -H "Costa-Audit-Enabled: true" \
    -d '{
      "model": "costa/compliance-assistant",
      "messages": [
        {
          "role": "user",
          "content": "Analyze this healthcare data processing code for HIPAA violations"
        }
      ],
      "max_tokens": 1500,
      "temperature": 0.2
    }'
  ```
</CodeGroup>

## Popular AI Agent Integrations

### AutoGPT Integration

<CodeGroup>
  ```yaml AutoGPT Configuration theme={null}
  ai_provider: custom
  api_base: https://ai.costa.app/api/v1
  api_key: costa_ent_your_key_here

  models:
    fast_llm: costa/enterprise-coder-v1
    smart_llm: costa/secure-claude-3-5-sonnet
    
  security:
    audit_enabled: true
    data_residency: us-east
    security_level: high

  headers:
    Costa-Security-Level: high
    Costa-Audit-Enabled: "true"
    Costa-Data-Residency: us-east
  ```

  ```python AutoGPT Custom Provider theme={null}
  class CostaCodeProvider:
      def __init__(self, api_key):
          self.api_key = api_key
          self.base_url = "https://ai.costa.app/api/v1"
      
      def chat_completion_request(self, model, messages, **kwargs):
          headers = {
              "Authorization": f"Bearer {self.api_key}",
              "Content-Type": "application/json",
              "Costa-Security-Level": "high",
              "Costa-Audit-Enabled": "true"
          }
          
          payload = {
              "model": model,
              "messages": messages,
              **kwargs
          }
          
          response = requests.post(
              f"{self.base_url}/chat/completions",
              headers=headers,
              json=payload
          )
          
          return response.json()
  ```
</CodeGroup>

### LangChain Integration

<CodeGroup>
  ```python LangChain Setup theme={null}
  from langchain.llms import OpenAI
  from langchain.chat_models import ChatOpenAI
  from langchain.schema import HumanMessage

  # Configure Costa as LangChain provider
  costa_llm = ChatOpenAI(
      openai_api_key="costa_ent_your_key_here",
      openai_api_base="https://ai.costa.app/api/v1",
      model_name="costa/enterprise-coder-v1",
      temperature=0.7
  )

  # Use with LangChain chains
  from langchain.chains import LLMChain
  from langchain.prompts import PromptTemplate

  prompt = PromptTemplate(
      input_variables=["task"],
      template="Write secure, enterprise-grade code for: {task}"
  )

  chain = LLMChain(llm=costa_llm, prompt=prompt)
  result = chain.run(task="user authentication system with MFA")

  # Enterprise security configuration
  costa_secure = ChatOpenAI(
      openai_api_key="costa_ent_your_key_here",
      openai_api_base="https://ai.costa.app/api/v1",
      model_name="costa/secure-claude-3-5-sonnet",
      model_kwargs={
          "extra_headers": {
              "Costa-Security-Level": "maximum",
              "Costa-Audit-Enabled": "true"
          }
      }
  )
  ```

  ```python LangChain Custom Integration theme={null}
  from langchain.llms.base import LLM
  from typing import Optional, List, Any
  import requests

  class CostaCodeLLM(LLM):
      api_key: str
      model: str = "costa/enterprise-coder-v1"
      security_level: str = "high"
      
      @property
      def _llm_type(self) -> str:
          return "costa-code"
      
      def _call(
          self,
          prompt: str,
          stop: Optional[List[str]] = None,
          run_manager: Optional[Any] = None,
          **kwargs: Any,
      ) -> str:
          headers = {
              "Authorization": f"Bearer {self.api_key}",
              "Content-Type": "application/json",
              "Costa-Security-Level": self.security_level,
              "Costa-Audit-Enabled": "true"
          }
          
          payload = {
              "model": self.model,
              "messages": [{"role": "user", "content": prompt}],
              "max_tokens": kwargs.get("max_tokens", 1000),
              "temperature": kwargs.get("temperature", 0.7)
          }
          
          response = requests.post(
              "https://ai.costa.app/api/v1/chat/completions",
              headers=headers,
              json=payload
          )
          
          return response.json()["choices"][0]["message"]["content"]

  # Usage
  costa_llm = CostaCodeLLM(
      api_key="costa_ent_your_key_here",
      model="costa/compliance-assistant",
      security_level="maximum"
  )
  ```
</CodeGroup>

### Custom AI Agent Template

<CodeGroup>
  ```python Generic AI Agent Template theme={null}
  import requests
  import json
  from typing import Dict, List, Optional

  class EnterpriseAIAgent:
      def __init__(self, api_key: str, default_model: str = "costa/enterprise-coder-v1"):
          self.api_key = api_key
          self.base_url = "https://ai.costa.app/api/v1"
          self.default_model = default_model
          self.session = requests.Session()
          self.session.headers.update({
              "Authorization": f"Bearer {api_key}",
              "Content-Type": "application/json"
          })
      
      def execute_task(
          self, 
          task: str, 
          model: Optional[str] = None,
          security_level: str = "high",
          compliance_frameworks: List[str] = None,
          **kwargs
      ) -> Dict:
          """Execute AI task with enterprise security"""
          
          headers = {
              "Costa-Security-Level": security_level,
              "Costa-Audit-Enabled": "true",
              "Costa-Data-Residency": kwargs.get("region", "us-east")
          }
          
          if kwargs.get("zero_retention", False):
              headers["Costa-Zero-Retention"] = "true"
          
          if compliance_frameworks:
              headers["Costa-Compliance-Frameworks"] = ",".join(compliance_frameworks)
          
          payload = {
              "model": model or self.default_model,
              "messages": [{"role": "user", "content": task}],
              "max_tokens": kwargs.get("max_tokens", 1000),
              "temperature": kwargs.get("temperature", 0.7)
          }
          
          response = self.session.post(
              f"{self.base_url}/chat/completions",
              headers=headers,
              json=payload
          )
          
          response.raise_for_status()
          return response.json()
      
      def code_review(self, code: str, framework: str = "general") -> Dict:
          """Perform security-focused code review"""
          
          model_map = {
              "hipaa": "costa/compliance-assistant",
              "sox": "costa/compliance-assistant", 
              "pci": "costa/compliance-assistant",
              "general": "costa/secure-claude-3-5-sonnet"
          }
          
          task = f"Perform a comprehensive security review of this code for {framework} compliance:\n\n{code}"
          
          return self.execute_task(
              task=task,
              model=model_map.get(framework, "costa/secure-claude-3-5-sonnet"),
              security_level="maximum",
              compliance_frameworks=[framework] if framework != "general" else [],
              zero_retention=True
          )
      
      def generate_code(self, requirements: str, language: str = "python") -> Dict:
          """Generate enterprise-grade code"""
          
          task = f"Generate secure, enterprise-grade {language} code for: {requirements}"
          
          return self.execute_task(
              task=task,
              model="costa/enterprise-coder-v1",
              security_level="high",
              max_tokens=2000
          )

  # Usage example
  agent = EnterpriseAIAgent("costa_ent_your_key_here")

  # Generate secure code
  code_result = agent.generate_code(
      "User authentication system with JWT and rate limiting",
      language="python"
  )

  # Review code for compliance
  review_result = agent.code_review(
      code="def process_payment(card_data): ...",
      framework="pci"
  )

  print("Generated code:", code_result["choices"][0]["message"]["content"])
  print("Security review:", review_result["choices"][0]["message"]["content"])
  ```
</CodeGroup>

## Enterprise Headers Reference

<AccordionGroup>
  <Accordion title="Security Level Control" icon="shield">
    **Header**: `Costa-Security-Level`

    **Values**:

    * `standard` - Default security measures
    * `high` - Enhanced security protocols
    * `maximum` - Highest security, compliance mode

    **Usage**:

    ```bash theme={null}
    -H "Costa-Security-Level: maximum"
    ```
  </Accordion>

  <Accordion title="Data Residency" icon="globe">
    **Header**: `Costa-Data-Residency`

    **Values**:

    * `us-east` - US East Coast
    * `us-west` - US West Coast
    * `eu-west` - European Union
    * `asia-pacific` - Asia Pacific

    **Usage**:

    ```bash theme={null}
    -H "Costa-Data-Residency: eu-west"
    ```
  </Accordion>

  <Accordion title="Audit Logging" icon="file-lines">
    **Header**: `Costa-Audit-Enabled`

    **Values**: `true`, `false`

    **Usage**:

    ```bash theme={null}
    -H "Costa-Audit-Enabled: true"
    ```
  </Accordion>

  <Accordion title="Zero Retention" icon="trash">
    **Header**: `Costa-Zero-Retention`

    **Values**: `true`, `false`

    **Description**: Enable zero data retention mode

    **Usage**:

    ```bash theme={null}
    -H "Costa-Zero-Retention: true"
    ```
  </Accordion>

  <Accordion title="Compliance Frameworks" icon="gavel">
    **Header**: `Costa-Compliance-Frameworks`

    **Values**: Comma-separated list of `hipaa`, `sox`, `pci-dss`, `gdpr`

    **Usage**:

    ```bash theme={null}
    -H "Costa-Compliance-Frameworks: hipaa,sox"
    ```
  </Accordion>
</AccordionGroup>

## Error Handling

<CodeGroup>
  ```python Error Handling Example theme={null}
  import requests
  from requests.exceptions import RequestException

  def safe_costa_request(api_key, model, messages, **kwargs):
      """Make a safe request to Costa API with error handling"""
      
      headers = {
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json",
          "Costa-Security-Level": kwargs.get("security_level", "high"),
          "Costa-Audit-Enabled": "true"
      }
      
      payload = {
          "model": model,
          "messages": messages,
          "max_tokens": kwargs.get("max_tokens", 1000),
          "temperature": kwargs.get("temperature", 0.7)
      }
      
      try:
          response = requests.post(
              "https://ai.costa.app/api/v1/chat/completions",
              headers=headers,
              json=payload,
              timeout=30
          )
          
          # Handle HTTP errors
          if response.status_code == 401:
              raise Exception("Invalid API key or authentication failed")
          elif response.status_code == 403:
              raise Exception("Access denied - check model permissions")
          elif response.status_code == 429:
              raise Exception("Rate limit exceeded - please retry later")
          elif response.status_code >= 500:
              raise Exception("Costa service error - please retry")
          
          response.raise_for_status()
          return response.json()
          
      except RequestException as e:
          raise Exception(f"Network error: {str(e)}")
      except Exception as e:
          raise Exception(f"API request failed: {str(e)}")

  # Usage with error handling
  try:
      result = safe_costa_request(
          api_key="costa_ent_your_key_here",
          model="costa/enterprise-coder-v1",
          messages=[{"role": "user", "content": "Generate secure code"}],
          security_level="high"
      )
      print("Success:", result["choices"][0]["message"]["content"])
      
  except Exception as e:
      print("Error:", str(e))
  ```
</CodeGroup>

## Testing & Validation

<CodeGroup>
  ```python API Testing Suite theme={null}
  import unittest
  import requests

  class CostaCodeAPITest(unittest.TestCase):
      
      def setUp(self):
          self.api_key = "costa_ent_your_test_key_here"
          self.base_url = "https://ai.costa.app/api/v1"
          self.headers = {
              "Authorization": f"Bearer {self.api_key}",
              "Content-Type": "application/json"
          }
      
      def test_basic_completion(self):
          """Test basic chat completion"""
          payload = {
              "model": "costa/enterprise-coder-v1",
              "messages": [{"role": "user", "content": "Hello, world!"}],
              "max_tokens": 50
          }
          
          response = requests.post(
              f"{self.base_url}/chat/completions",
              headers=self.headers,
              json=payload
          )
          
          self.assertEqual(response.status_code, 200)
          data = response.json()
          self.assertIn("choices", data)
          self.assertGreater(len(data["choices"]), 0)
      
      def test_security_headers(self):
          """Test enterprise security headers"""
          headers = {
              **self.headers,
              "Costa-Security-Level": "maximum",
              "Costa-Audit-Enabled": "true"
          }
          
          payload = {
              "model": "costa/secure-claude-3-5-sonnet",
              "messages": [{"role": "user", "content": "Test security"}],
              "max_tokens": 50
          }
          
          response = requests.post(
              f"{self.base_url}/chat/completions",
              headers=headers,
              json=payload
          )
          
          self.assertEqual(response.status_code, 200)
          data = response.json()
          self.assertIn("security", data)
      
      def test_model_availability(self):
          """Test available models"""
          response = requests.get(
              f"{self.base_url}/models",
              headers=self.headers
          )
          
          self.assertEqual(response.status_code, 200)
          data = response.json()
          model_ids = [model["id"] for model in data["data"]]
          self.assertIn("costa/enterprise-coder-v1", model_ids)

  if __name__ == "__main__":
      unittest.main()
  ```
</CodeGroup>

## Best Practices

<Steps>
  <Step title="Authentication Security">
    * Store API keys securely using environment variables
    * Rotate API keys regularly
    * Use different keys for development and production
  </Step>

  <Step title="Error Handling">
    * Implement comprehensive error handling
    * Add retry logic for transient failures
    * Log errors for debugging and monitoring
  </Step>

  <Step title="Security Configuration">
    * Use appropriate security levels for your use case
    * Enable audit logging for compliance requirements
    * Configure data residency based on regulations
  </Step>

  <Step title="Performance Optimization">
    * Use streaming for real-time applications
    * Cache responses when appropriate
    * Monitor usage and optimize model selection
  </Step>
</Steps>

***

<Warning>
  **Enterprise Integration**: When integrating Costa with AI agents, ensure proper security measures are implemented including secure API key storage, appropriate security levels, and compliance configuration for your industry requirements.
</Warning>

{user.firstName}