Endpoints

This reference documents all available endpoints in the Flux API Gateway.

Base URL

https://useflux.site/api/v2

API Management

List All APIs

GET /apis

Returns a paginated list of all available APIs.

Response:

{
  "apis": [
    {
      "id": "api_123",
      "name": "Weather API",
      "provider": "0x...",
      "pricePerRequest": "0.001",
      "currency": "ETH",
      "endpoint": "https://api.weather.example.com",
      "description": "Real-time weather data"
    }
  ],
  "total": 42,
  "page": 1
}

Get API Details

GET /apis/{apiId}

Retrieve detailed information about a specific API.

Parameters:

• apiId (string, required) — The API identifier

Response:

{
  "id": "api_123",
  "name": "Weather API",
  "provider": "0x...",
  "pricePerRequest": "0.001",
  "currency": "ETH",
  "endpoint": "https://api.weather.example.com",
  "description": "Real-time weather data",
  "openapi": { /* OpenAPI spec */ }
}

Create API

POST /apis

Create a new API listing. Requires wallet authentication.

Request Body:

{
  "name": "Weather API",
  "endpoint": "https://api.weather.example.com",
  "pricePerRequest": "0.001",
  "currency": "ETH",
  "description": "Real-time weather data",
  "openapi": { /* OpenAPI specification */ }
}

Response: Returns the created API object with ID.

Update API

PUT /apis/{apiId}

Update an existing API. Only the provider can update their own API.

Parameters:

• apiId (string, required) — The API identifier

Request Body: Same as Create API

Discovery

Get API Discovery Information

GET /apis/{apiId}/discovery

Retrieve structured discovery information for AI agents, including OpenAPI spec and pricing.

Parameters:

• apiId (string, required) — The API identifier

Response:

{
  "id": "api_123",
  "name": "Weather API",
  "description": "Real-time weather data",
  "pricePerRequest": "0.001",
  "currency": "ETH",
  "provider": "0x...",
  "openapi": { /* Full OpenAPI specification */ },
  "agentInfo": {
    "capabilities": ["weather-lookup", "forecast"],
    "requiredHeaders": ["X-Payment-Tx", "X-Signature"]
  }
}

Get Agent Info

GET /apis/{apiId}/agent-info

Get agent-specific information for autonomous integration.

Parameters:

• apiId (string, required) — The API identifier

Response:

{
  "capabilities": ["weather-lookup", "forecast"],
  "requiredHeaders": ["X-Payment-Tx", "X-Signature"],
  "paymentAddress": "0x...",
  "supportedChains": ["base", "polygon", "ethereum"]
}

Gateway

Call API Through Gateway

POST /gateway/{apiId}/{path}

Route a request through the Flux gateway to the target API. Requires valid payment proof.

Parameters:

• apiId (string, required) — The API identifier

• path (string, required) — The target API path

Headers:

• X-Payment-Tx (string, required) — Transaction hash proving payment

• X-Signature (string, required) — ECDSA signature of the transaction

• Content-Type (string) — Request content type

Response: Proxied response from the target API

History

Get Call History

GET /history

Retrieve the call history for the authenticated user.

Query Parameters:

• apiId (string, optional) — Filter by API

• limit (number, optional) — Number of records to return (default: 50)

• offset (number, optional) — Pagination offset (default: 0)

Response:

{
  "calls": [
    {
      "id": "call_123",
      "apiId": "api_123",
      "timestamp": "2025-01-15T10:30:00Z",
      "status": "success",
      "paymentTx": "0x...",
      "cost": "0.001"
    }
  ],
  "total": 156
}

Error Responses

All endpoints return standard error responses. See Error Codes for details.

Standard Error Format:

{
  "error": "INVALID_PAYMENT",
  "message": "Payment transaction not found on chain",
  "code": 400
}