API Examples

Complete examples for common API use cases. Use these examples to integrate Solo with your applications.

Authentication

cURL

curl -X GET https://solomail.io/api/v1/identity \
  -H "Authorization: Bearer <your-api-key>"

JavaScript

const apiKey = 'your-api-key-here'

async function getIdentity() {
  const response = await fetch('https://solomail.io/api/v1/identity', {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  })
  
  const data = await response.json()
  return data
}

Python

import requests

api_key = 'your-api-key-here'
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://solomail.io/api/v1/identity',
    headers=headers
)

data = response.json()

Update Identity Profile

Update Profile Tagline

cURL:

curl -X PATCH https://solomail.io/api/v1/identity \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "tagline": "Your trusted partner for innovative solutions"
    }
  }'

JavaScript:

async function updateProfileTagline(tagline) {
  const response = await fetch('https://solomail.io/api/v1/identity', {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      profile: {
        tagline: tagline
      }
    })
  })
  
  return await response.json()
}

Python:

def update_profile_tagline(tagline):
    response = requests.patch(
        'https://solomail.io/api/v1/identity',
        headers=headers,
        json={
            'profile': {
                'tagline': tagline
            }
        }
    )
    return response.json()

Add a Service

cURL:

curl -X PATCH https://solomail.io/api/v1/identity \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "services": [
        {
          "name": "Consulting Session",
          "description": "One-on-one consulting session",
          "price": 150.00,
          "currency": "USD",
          "billingInterval": "one-time",
          "active": true
        }
      ]
    }
  }'

JavaScript:

async function addService(service) {
  const response = await fetch('https://solomail.io/api/v1/identity', {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      profile: {
        services: [service]
      }
    })
  })
  
  return await response.json()
}

// Usage
addService({
  name: "Consulting Session",
  description: "One-on-one consulting session",
  price: 150.00,
  currency: "USD",
  billingInterval: "one-time",
  active: true
})

Python:

def add_service(service):
    response = requests.patch(
        'https://solomail.io/api/v1/identity',
        headers=headers,
        json={
            'profile': {
                'services': [service]
            }
        }
    )
    return response.json()

# Usage
add_service({
    'name': 'Consulting Session',
    'description': 'One-on-one consulting session',
    'price': 150.00,
    'currency': 'USD',
    'billingInterval': 'one-time',
    'active': True
})

Update Multiple Profile Fields

cURL:

curl -X PATCH https://solomail.io/api/v1/identity \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Acme Inc",
    "profile": {
      "tagline": "Your trusted partner",
      "about": "We provide innovative solutions for businesses worldwide.",
      "website": "https://example.com"
    }
  }'

JavaScript:

async function updateProfile(updates) {
  const response = await fetch('https://solomail.io/api/v1/identity', {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(updates)
  })
  
  return await response.json()
}

// Usage
updateProfile({
  displayName: "Acme Inc",
  profile: {
    tagline: "Your trusted partner",
    about: "We provide innovative solutions for businesses worldwide.",
    website: "https://example.com"
  }
})

Usage Tracking

Track Token Usage

cURL:

curl -X POST https://solomail.io/api/v1/usage/track \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "token_usage",
    "identityId": "identity-id",
    "promptTokens": 100,
    "completionTokens": 50,
    "totalTokens": 150,
    "model": "gpt-4",
    "provider": "openai",
    "usageType": "workflow",
    "operation": "email_processing",
    "agentId": "agent-id"
  }'

JavaScript:

async function trackTokenUsage(usageData) {
  const response = await fetch('https://solomail.io/api/v1/usage/track', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'token_usage',
      identityId: 'identity-id',
      promptTokens: 100,
      completionTokens: 50,
      totalTokens: 150,
      model: 'gpt-4',
      provider: 'openai',
      usageType: 'workflow',
      operation: 'email_processing',
      agentId: 'agent-id',
      ...usageData
    })
  })
  
  return await response.json()
}

Python:

def track_token_usage(usage_data):
    response = requests.post(
        'https://solomail.io/api/v1/usage/track',
        headers=headers,
        json={
            'type': 'token_usage',
            'identityId': 'identity-id',
            'promptTokens': 100,
            'completionTokens': 50,
            'totalTokens': 150,
            'model': 'gpt-4',
            'provider': 'openai',
            'usageType': 'workflow',
            'operation': 'email_processing',
            'agentId': 'agent-id',
            **usage_data
        }
    )
    return response.json()

Track Agent Execution

cURL:

curl -X POST https://solomail.io/api/v1/usage/track \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "agent_execution",
    "identityId": "identity-id",
    "agentId": "agent-id",
    "status": "completed",
    "operation": "send_email",
    "result": {
      "success": true,
      "emailSent": true
    }
  }'

JavaScript:

async function trackAgentExecution(executionData) {
  const response = await fetch('https://solomail.io/api/v1/usage/track', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'agent_execution',
      identityId: 'identity-id',
      agentId: 'agent-id',
      status: 'completed',
      operation: 'send_email',
      result: {
        success: true,
        emailSent: true
      },
      ...executionData
    })
  })
  
  return await response.json()
}

Get Usage Statistics

cURL:

curl -X GET https://solomail.io/api/v1/usage/stats \
  -H "Authorization: Bearer <your-api-key>"

JavaScript:

async function getUsageStats() {
  const response = await fetch('https://solomail.io/api/v1/usage/stats', {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  })
  
  return await response.json()
}

Workflow Tool Integration

Example: n8n Workflow

{
  "nodes": [
    {
      "name": "Solo API - Track Usage",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "method": "POST",
        "url": "https://solomail.io/api/v1/usage/track",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer {{ $env.SOLO_API_KEY }}"
            },
            {
              "name": "Content-Type",
              "value": "application/json"
            }
          ]
        },
        "sendBody": true,
        "bodyParameters": {
          "parameters": [
            {
              "name": "type",
              "value": "token_usage"
            },
            {
              "name": "identityId",
              "value": "={{ $json.identityId }}"
            },
            {
              "name": "promptTokens",
              "value": "={{ $json.promptTokens }}"
            },
            {
              "name": "completionTokens",
              "value": "={{ $json.completionTokens }}"
            },
            {
              "name": "totalTokens",
              "value": "={{ $json.totalTokens }}"
            },
            {
              "name": "model",
              "value": "={{ $json.model }}"
            },
            {
              "name": "provider",
              "value": "={{ $json.provider }}"
            }
          ]
        }
      }
    }
  ]
}

Error Handling

JavaScript Error Handling

async function apiCall(endpoint, options = {}) {
  try {
    const response = await fetch(`https://solomail.io/api/v1${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    })
    
    if (!response.ok) {
      const error = await response.json()
      throw new Error(error.error || 'API request failed')
    }
    
    return await response.json()
  } catch (error) {
    console.error('API Error:', error)
    throw error
  }
}

Python Error Handling

import requests
from requests.exceptions import RequestException

def api_call(endpoint, method='GET', data=None):
    try:
        url = f'https://solomail.io/api/v1{endpoint}'
        response = requests.request(
            method,
            url,
            headers=headers,
            json=data
        )
        response.raise_for_status()
        return response.json()
    except RequestException as e:
        print(f'API Error: {e}')
        raise

Next Steps

• Learn about Authentication
• Explore API Endpoints
• Understand Webhooks

---

Version: 1.2.0
Last Updated: November 2025