API Endpoints

Solo's API provides endpoints for managing identities, agents, workflows, and usage tracking.

Base URL

All API requests use this base URL:

https://solomail.io/api/v1

Endpoints

Identity Endpoints

Get Identity

Get information about your Solo Identity.

Endpoint: GET /identity

Headers:

Authorization: Bearer <your-api-key>

Response:

{
  "id": "identity-id",
  "handle": "yourname",
  "address": "yourname@solomail.io",
  "scope": "business",
  "displayName": "Acme Inc",
  "profile": {
    "tagline": "Your trusted partner for innovative solutions",
    "about": "We are a leading provider of...",
    "website": "https://example.com",
    "services": [
      {
        "id": "service-uuid",
        "name": "Consulting Session",
        "description": "One-on-one consulting session",
        "price": 150.00,
        "currency": "USD",
        "billingInterval": "one-time",
        "active": true
      }
    ]
  },
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-11T12:00:00Z"
}

Response Fields:

• id (string) - Identity UUID
• handle (string) - Unique handle
• address (string | null) - SoloMail address
• scope (string) - Identity scope: "identity" or "business"
• displayName (string | null) - Display name for the identity
• profile (object | null) - Profile information (see Profile Structure below)
• createdAt (string) - ISO 8601 timestamp
• updatedAt (string | null) - ISO 8601 timestamp

Profile Structure: The profile object contains:

• tagline (string, optional) - Short one-liner describing the identity
• about (string, optional) - Detailed description (max 1000 characters)
• website (string, optional) - Website URL
• services (array, optional) - Array of services/products offered:
  • id (string) - Service UUID
  • name (string) - Service name
  • description (string, optional) - Service description
  • price (number) - Price amount
  • currency (string) - Currency code (e.g., "USD", "EUR", "GBP")
  • billingInterval (string) - "one-time" | "monthly" | "yearly"
  • active (boolean) - Whether the service is currently active

Update Identity Profile

Update identity profile information. Supports partial updates - only include fields you want to update.

Endpoint: PATCH /identity

Headers:

Authorization: Bearer <your-api-key>
Content-Type: application/json

Request Body:

{
  "displayName": "Acme Inc",
  "profile": {
    "tagline": "Your trusted partner",
    "about": "We provide innovative solutions...",
    "website": "https://example.com",
    "services": [
      {
        "id": "service-uuid",
        "name": "Consulting Session",
        "description": "One-on-one consulting",
        "price": 150.00,
        "currency": "USD",
        "billingInterval": "one-time",
        "active": true
      }
    ]
  }
}

Request Fields:

• displayName (string | null, optional) - Update display name
• profile (object, optional) - Update profile fields (merges with existing profile):
  • tagline (string, optional)
  • about (string, optional, max 1000 characters)
  • website (string, optional)
  • services (array, optional) - Array of services (see Profile Structure above)

Note: The profile object is merged with existing profile data. To remove a field, set it to null or omit it from the request.

Response: Returns the updated identity object (same structure as GET /identity).

Example: Update Tagline Only

{
  "profile": {
    "tagline": "New tagline here"
  }
}

Example: Add a Service

{
  "profile": {
    "services": [
      {
        "name": "New Service",
        "description": "Service description",
        "price": 99.99,
        "currency": "USD",
        "billingInterval": "monthly",
        "active": true
      }
    ]
  }
}

Note: When updating services, you can provide services without id fields - they will be auto-generated. To update an existing service, include its id.

Error Responses:

400 Bad Request - Invalid request body:

{
  "error": "Invalid request body",
  "message": "Request body must be a JSON object"
}

404 Not Found - Identity not found:

{
  "error": "Identity not found"
}

Usage Tracking Endpoints

Track Token Usage

Record token usage from workflows.

Endpoint: POST /usage/track

Headers:

Authorization: Bearer <your-api-key>
Content-Type: application/json

Request Body:

{
  "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",
  "conversationId": "conversation-id",
  "taskId": "task-id",
  "metadata": {
    "workflow": "inbox-manager",
    "step": "analyze_email"
  }
}

Response:

{
  "success": true,
  "id": "usage-id",
  "createdAt": "2025-01-01T00:00:00Z"
}

Track Agent Execution

Record agent execution events.

Endpoint: POST /usage/track

Headers:

Authorization: Bearer <your-api-key>
Content-Type: application/json

Request Body:

{
  "type": "agent_execution",
  "identityId": "identity-id",
  "agentId": "agent-id",
  "status": "completed",
  "operation": "send_email",
  "conversationId": "conversation-id",
  "taskId": "task-id",
  "messageId": "message-id",
  "result": {
    "success": true,
    "emailSent": true
  },
  "metadata": {
    "workflow": "inbox-manager",
    "duration": 1.5
  }
}

Response:

{
  "success": true,
  "id": "execution-id",
  "createdAt": "2025-01-01T00:00:00Z"
}

Get Usage Statistics

Get current usage statistics.

Endpoint: GET /usage/stats

Headers:

Authorization: Bearer <your-api-key>

Response:

{
  "tokenUsage": {
    "current": 50000,
    "limit": 1000000,
    "percentage": 5,
    "formatted": "50K / 1M"
  },
  "executions": {
    "current": 150,
    "limit": 300,
    "percentage": 50,
    "formatted": "150 / 300"
  },
  "plan": "free"
}

Request Format

Headers

All requests require:

• Authorization: Bearer <your-api-key>
• Content-Type: application/json (for POST/PUT requests)

Request Body

POST and PUT requests include JSON body:

{
  "field": "value"
}

Response Format

Success Response

Status: 200 OK or 201 Created

{
  "success": true,
  "data": { ... }
}

Error Response

Status: 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error

{
  "error": "Error message",
  "details": { ... }
}

Error Codes

Rate Limits

Rate limits are enforced per API key:

Rate limit headers included in responses:

• X-RateLimit-Limit: Total requests allowed
• X-RateLimit-Remaining: Requests remaining
• X-RateLimit-Reset: Unix timestamp when limit resets

Next Steps

• Learn about Authentication
• Explore Webhooks
• See API Examples

---

Version: 1.2.0
Last Updated: November 2025