API Reference

The Echo V1 API provides programmatic access for SDKs, CLI tools, and applications. All endpoints are prefixed with /api/v1/.

Authentication

The V1 API supports two authentication methods:

API Keys

API keys are the primary authentication method for programmatic access. Include your API key in the request header:

Authorization: Bearer your_api_key_here

JWT Tokens

JWT tokens are used for OAuth flows and temporary access. Include JWT tokens in either header:

Authorization: Bearer your_jwt_token_here

or

X-Echo-Token: your_jwt_token_here

Applications

List User Apps

GET /api/v1/apps

List all Echo apps owned by the authenticated user.

Authentication: API key or JWT token required

Response Type:

{
  items: Array<App>;
  has_next: boolean;
  page: number;
  page_size: number;
  total_count: number;
}

GET /api/v1/apps/{id}

Get detailed app information for programmatic access.

Authentication: API key or JWT token required
Path Parameters:

• id (UUID) - App ID

Response Type:

Balance & Billing

Get User Balance

GET /api/v1/balance

Get authenticated user's credit balance.

Authentication: API key or JWT token required
Query Parameters:

• echoAppId (UUID, optional) - Get app-specific balance instead of global

Response Type:

Get Free Tier Balance

POST /api/v1/balance/{appId}/free

Get user's free tier spending information for a specific app.

Authentication: API key or JWT token required

Response Type:

{
  spendPoolBalance: number;
  userSpendInfo: UserSpendInfo;
}

Payments

Create Payment Link

POST /api/v1/stripe/payment-link

Generate Stripe payment link for credit purchases.

Authentication: API key or JWT token required

Request Body:

{
  amount: number;
  successUrl?: string;
}

Response Type:

{
  paymentUrl: string;
  sessionId: string;
  expiresAt: string;
}

Models & Capabilities

Get Supported Models

GET /api/v1/supported-models

Get list of supported AI models with pricing information.

Authentication: None required

Response Type:

{
  models: SupportedModel[];
  models_by_provider: Record<string, string[]>;
}

SupportedModel Interface:

interface SupportedModel {
  id: string;
  name: string;
  provider: string;
  inputPrice: number;
  outputPrice: number;
  contextLength: number;
}

User Management

Get User Info

GET /api/v1/user

Get authenticated user profile information.

Authentication: API key or JWT token required

Response Type:

{
  id: string;
  email: string;
  name: string | null;
  createdAt: string;
  updatedAt: string;
  totalPaid: number;
  totalSpent: number;
}

Register Referral Code

POST /api/v1/user/referral

Apply a referral code for credits on a specific app.

Authentication: API key or JWT token required

Request Body:

{
  echoAppId: string;
  code: string;
}

Response Type:

{
  success: boolean;
  message: string;
  creditsAwarded?: number;
}

Error Responses

All endpoints return appropriate HTTP status codes and JSON error responses:

{
  "error": "string",
  "message": "string",
  "statusCode": "number"
}

Common Status Codes

• 200 OK - Success
• 201 Created - Resource created
• 400 Bad Request - Invalid request data
• 401 Unauthorized - Authentication required
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error