API Reference

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

All API endpoints use JSON request/response format. Most endpoints require authentication via API keys or JWT tokens.

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

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:

{
  apps: PublicEchoApp[]
}

Prop	Type	Default
`name`	`string`	-
`id`	`string`	-
`description`	`string \| null`	-
`profilePictureUrl`	`string \| null`	-
`bannerImageUrl`	`string \| null`	-
`homepageUrl`	`string \| null`	-
`isPublic`	`boolean`	-
`createdAt`	`Date`	-
`updatedAt`	`Date`	-
`currentReferralRewardId`	`string \| null`	-
`owner`	`Owner`	-
`stats`	`GlobalStatistics`	-
`githubLink?`	`AppGithubLink`	-
`type`	`"public"`	-

Get App Details

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: Returns a PublicEchoApp with detailed statistics

Prop	Type	Default
`globalTotalTransactions`	`number`	-
`globalTotalRevenue`	`number`	-
`globalTotalTokens`	`number`	-
`globalTotalInputTokens`	`number`	-
`globalTotalOutputTokens`	`number`	-
`globalActivityData`	`AppActivity[]`	-
`globalModelUsage`	`ModelUsage[]`	-
`globalFreeTierSpendPoolBalance`	`number`	-
`globalFreetierSpendPoolPerUserLimit`	`number \| null`	-

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:

Prop	Type	Default
`totalPaid`	`number`	-
`totalSpent`	`number`	-
`balance`	`number`	-
`currency`	`string`	-

For app-specific balance queries, returns:

Prop	Type	Default
`echoAppId`	`string`	-
`echoAppName`	`string`	-
`totalPaid`	`number`	-
`totalSpent`	`number`	-
`balance`	`number`	-
`currency`	`string`	-

Get Free Tier Balance

POST /api/v1/balance/free

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

Authentication: API key or JWT token required

Request Body:

{
  echoAppId: string
}

Response Type:

{
  spendPoolBalance: {
    available: number;
    total: number; 
    used: number;
  };
  userSpendInfo: UserSpendInfo;
}

Prop	Type	Default
`userId`	`string`	-
`echoAppId`	`string`	-
`spendPoolId`	`string \| null`	-
`amountSpent`	`number`	-
`spendLimit`	`number \| null`	-
`amountLeft`	`number`	-

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;
}

Payment amounts are in USD. The successUrl parameter is optional and will redirect users after successful payment.

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

All endpoints require HTTPS in production environments. UUID parameters are validated for proper format.

API Reference

On this page