API Reference

Complete reference for all Aphelion Gateway v2.0 API endpoints with examples and response formats.

Base URL

https://api.aphl.ai

Authentication

All endpoints (except system health and Auth0 info) require JWT authentication:

Authorization: Bearer <your-jwt-token>

See the Authentication guide for details on obtaining tokens.

Quick Reference

System

GET/healthHealth check

GET/API documentation

Authentication

GET/auth/infoGet Auth0 configuration

GET/auth/debugDebug JWT token

GET/auth/profileGet user profile

GET/auth/db-statusDatabase status

Service Registry

POST/owner/servicesRegister API service

GET/owner/servicesGet user services

GET/owner/services/{serviceId}Get service details

DELETE/owner/services/{serviceId}Delete service

GET/servicesList public services

GET/services/{serviceId}/manifestGet service manifest

Sessions & Execution

POST/v1/agentsCreate agent session

GET/v1/agentsGet user sessions

GET/v1/agents/{sessionId}Get session details

POST/v1/agents/{sessionId}/executeExecute tool

Subscriptions

POST/subscriptionsSubscribe to service

GET/subscriptionsGet user subscriptions

DELETE/subscriptions/{subscriptionId}Cancel subscription

GET/subscriptions/services/idsGet subscribed service IDs

Memory

GET/memoryGet user memories

GET/memory/paginatedGet paginated memories

GET/memory/searchSearch memories

GET/memory/context/agentGet agent context

GET/memory/sessions/{sessionId}/timelineGet session timeline

POST/memory/sessions/{sessionId}/summarizeCreate session summary

GET/memory/statsGet memory statistics

DELETE/memoryDelete all memories

Search

GET/searchUniversal search

GET/search/toolsSearch tools

GET/search/popularGet popular tools

GET/search/recommendationsGet recommendations

GET/search/suggestionsGet search suggestions

Analytics

GET/analytics/userGet user analytics

GET/analytics/systemGet system analytics

GET/analytics/toolsGet tool analytics

GET/analytics/realtimeGet real-time metrics

Common Endpoints

Health Check

GET/health

Response

{
  "status": "ok",
  "uptime": 3600,
  "version": "2.0.0",
  "timestamp": "2025-06-21T10:00:00Z"
}

Execute Tool

POST/v1/agents/{sessionId}/execute

Request

{
  "tool": "weather.api.get_current_weather",
  "params": {
    "location": "San Francisco"
  }
}

Response

{
  "id": "execution-uuid",
  "tool_name": "weather.api.get_current_weather",
  "parameters": {
    "location": "San Francisco"
  },
  "result": {
    "temperature": 72,
    "condition": "sunny",
    "humidity": 65
  },
  "execution_time": 245,
  "cost": 0.002,
  "created_at": "2025-06-21T10:00:00Z"
}

Built-in Tools

These tools are always available in every session:

Echo

{
  "tool": "echo",
  "params": {
    "message": "Hello World"
  }
}

Calculate

{
  "tool": "calculate",
  "params": {
    "expression": "2 + 2 * 3"
  }
}

Get Current Time

{
  "tool": "get_current_time",
  "params": {}
}

Error Responses

All endpoints return structured error responses:

400Bad Request

{
  "error": "Invalid request parameters",
  "details": "Missing required field: location",
  "code": "VALIDATION_ERROR"
}

401Unauthorized

{
  "error": "Authentication required",
  "code": "MISSING_AUTHORIZATION"
}

403Forbidden

{
  "error": "Access denied",
  "details": "Insufficient permissions for this operation",
  "code": "ACCESS_DENIED"
}

404Not Found

{
  "error": "Resource not found",
  "details": "Service with ID 'invalid-uuid' does not exist",
  "code": "RESOURCE_NOT_FOUND"
}

429Too Many Requests

{
  "error": "Rate limit exceeded",
  "details": "Maximum 100 requests per hour exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 3600
}

500Internal Server Error

{
  "error": "Internal server error",
  "details": "An unexpected error occurred",
  "code": "INTERNAL_ERROR"
}

Rate Limits

Endpoint Category	Rate Limit
Authentication	10 requests per minute
Service Registration	5 requests per minute
Tool Execution (Free tier)	100 requests per hour
Memory Operations	50 requests per minute
Analytics	20 requests per minute

ℹ️Rate Limit Headers

Check response headers X-RateLimit-Remaining and X-RateLimit-Resetto monitor your rate limit status.

Request/Response Headers

Request Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>
User-Agent: aphelion-frontend/2.0.0

Response Headers

Content-Type: application/json
X-Request-ID: request-uuid
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

SDKs & Tools

go get github.com/aphelion/go-sdk

Postman Collection

Import the provided Postman collection for interactive testing:

• Complete Auth0 authentication flow
• All endpoint examples with proper authentication
• Environment variables for easy testing
• Pre-request scripts for token management

Support

Need help with the API? We're here to assist.

Discord Community →GitHub Issues →api-support@aphl.ai →