Overview
The `/developers` entry point makes the supported Eternal workflows directly usable from an application, backend service, script, or agent. It exposes a stable public API surface with API-key authentication.
Full API documentation: https://eternal-agents.com/developers/docs
On LLM-powered endpoints, you can pass `model_name` per request. If you do not, the API simply uses the default model associated with the account or API key.
Authentication
Create API keys from /account/api-keys. Once created, the key can call every `/developers` route allowed by your plan.
Two authentication formats are accepted. `X-API-Key` works well for straightforward integrations. `Authorization: Bearer` is useful if your stack already standardizes on that format.
LLM Models
The `/llm-models` route returns the official list of supported `model_name` values. It includes the model name, provider, relative cost factor, and whether the model is the default.
curl https://eternal-agents.com/developers/llm-models -H "X-API-Key: YOUR_API_KEY"Use this route to discover valid model names before building dynamic requests.
[
{
"name": "gemini-2.5-flash-lite",
"provider": "vertex",
"provider_label": "Gemini",
"version": null,
"factor": 1,
"logo": "/gemini-logo.png",
"is_default": true
},
{
"name": "gpt-5-mini",
"provider": "azure",
"provider_label": "OpenAI",
"version": "2025-08-07",
"factor": 3,
"logo": "/openai-logo.png",
"is_default": false
}
]Example response excerpt.
Quickstart
The simplest first call is a decode request. It verifies authentication, response shape, and model selection in one concrete step.
curl -X POST https://eternal-agents.com/developers/api/v1/decode -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"asset": "SPY", "timeframe": "6M", "model_name": "gpt-5-mini"}'A successful response returns a `session_id`, structured analysis, and can then be extended with `chat` or technical endpoints.
SDK
const API_KEY = process.env.ETERNAL_API_KEY;
const baseUrl = "https://eternal-agents.com/developers";
const response = await fetch(
baseUrl + "/compare/cross-asset?assets=SPY,TLT,GLD&timeframe=1W&model_name=gpt-5-mini",
{
headers: { "X-API-Key": API_KEY }
}
);
const data = await response.json();A `fetch` example for a GET route using a model override.
import requests
api_key = "YOUR_API_KEY"
base_url = "https://eternal-agents.com/developers"
r = requests.get(
f"{base_url}/narrative/current?model_name=gpt-5-mini",
headers={"X-API-Key": api_key},
timeout=60,
)
print(r.json())A `requests` example for a simple narrative route.
Decode + Technical
This family covers the main decode workflow, follow-up questions inside a session context, saved session retrieval, asynchronous jobs, and technical enrichments tied to an existing analysis.
curl -X POST https://eternal-agents.com/developers/api/v1/chat -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{
"session_id": "decode_01HZXA8Q3X3M4NT8P6QJ7R2S1T",
"question": "What historically tends to break this regime?",
"model_name": "gpt-5-mini"
}'Typical flow: decode an asset, continue with `chat`, then use technical endpoints when you want to inspect a structure or indicator in more detail.
Primary routes
https://eternal-agents.com/developers/api/v1/decodehttps://eternal-agents.com/developers/api/v1/chathttps://eternal-agents.com/developers/api/v1/decode/sessionshttps://eternal-agents.com/developers/api/v1/decode/session/{session_id}https://eternal-agents.com/developers/api/v1/decode/session/{session_id}https://eternal-agents.com/developers/api/v1/decode/session/{session_id}https://eternal-agents.com/developers/api/v1/decode/jobshttps://eternal-agents.com/developers/api/v1/decode/jobs/{job_id}https://eternal-agents.com/developers/api/v1/decode/jobs/{job_id}/cancelhttps://eternal-agents.com/developers/api/v1/technical/structure/{session_id}https://eternal-agents.com/developers/api/v1/technical/explain/{session_id}/{indicator_key}News + Reports
News reports are configurable per request. You choose the report window, explicit date range, assets, categories, language, and the model when you want to force a specific `model_name`.
Use the synchronous route for quicker reports, and the `jobs` routes when you prefer an asynchronous workflow with polling and cancellation.
curl -X POST https://eternal-agents.com/developers/news-reports -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{
"title": "Macro cross-asset pulse",
"timeframe_type": "weekly",
"start_date": "2026-03-18T00:00:00Z",
"end_date": "2026-03-25T00:00:00Z",
"assets": ["SPY", "TLT", "GLD"],
"categories": ["us_equities", "bonds"],
"language": "en",
"model_name": "gpt-5-mini"
}'An example of generating a multi-asset macro report with explicit dates, assets, categories, and model selection.
Primary routes
https://eternal-agents.com/developers/news/sourceshttps://eternal-agents.com/developers/news-reportshttps://eternal-agents.com/developers/news-reports/jobshttps://eternal-agents.com/developers/news-reports/jobs/{job_id}https://eternal-agents.com/developers/news-reports/jobs/{job_id}/cancelhttps://eternal-agents.com/developers/news-reportshttps://eternal-agents.com/developers/news-reports/{report_id}Lab + Sensei
The Laboratory API lets you initialize a portfolio, define an asset universe, configure strategy rules, run cycles, execute a full backtest, and work with Sensei from your own product.
Sensei is the strategy assistant. It helps formulate an allocation logic, propose constraints, and draft rules that can be reused in Lab.
curl -X POST https://eternal-agents.com/developers/api/v1/lab/initialize -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{
"inception_date": "2024-01-02",
"end_date": "2025-12-31",
"starting_capital": 250000,
"trading_fee_pct": 0.1,
"reset_journal": true,
"language": "en",
"use_all_assets": false,
"asset_universe": ["SPY", "TLT", "GLD", "QQQ", "UUP"],
"custom_strategy_rules": "Favor resilient trend exposure when liquidity is improving and inflation pressure is fading.",
"custom_strategy_constraints": "Max 35% in any one asset. Keep at least 10% in cash when confidence is below 0.55.",
"custom_strategy_strict_mode": true,
"custom_strategy_use_decode": true,
"custom_strategy_use_brief": true,
"custom_strategy_fail_fast": true,
"model_name": "gpt-5-mini"
}'A full initialization example with asset universe, strategy rules, constraints, validation settings, and model choice.
curl -X POST https://eternal-agents.com/developers/api/v1/lab/sensei/chat -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{
"messages": [
{
"role": "user",
"content": "Build me a regime-aware swing strategy for SPY, TLT, GLD, and UUP with tighter drawdown control."
}
],
"use_all_assets": false,
"asset_universe": ["SPY", "TLT", "GLD", "UUP"],
"current_strategy_rules": "Prefer pro-risk exposure only when liquidity and growth are aligned.",
"current_strategy_constraints": "Max 30% per asset. Keep minimum 10% cash in unstable regimes.",
"model_name": "gpt-5-mini"
}'Use this route to get draft strategy logic and structured constraints.
curl -X POST https://eternal-agents.com/developers/api/v1/lab/run-backtest-full -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model_name": "gpt-5-mini"}'The full backtest reuses the stored Lab configuration and can be pinned to a chosen model.
Primary routes
https://eternal-agents.com/developers/api/v1/lab/initializehttps://eternal-agents.com/developers/api/v1/lab/run-cyclehttps://eternal-agents.com/developers/api/v1/lab/run-backtest-fullhttps://eternal-agents.com/developers/api/v1/lab/sensei/chathttps://eternal-agents.com/developers/api/v1/lab/strategy-settingshttps://eternal-agents.com/developers/api/v1/lab/senseihttps://eternal-agents.com/developers/api/v1/lab/sensei/sessionsOther Tools
Beyond the primary workflows, the API also exposes Compare, Narrative, Monitoring, Scenarios, Research, a read-only regime library, personal-context endpoints, and price data.
curl "https://eternal-agents.com/developers/compare/cross-asset?assets=SPY,TLT,GLD&timeframe=1W&model_name=gpt-5-mini" -H "X-API-Key: YOUR_API_KEY"curl "https://eternal-agents.com/developers/narrative/drift?topic=AI%20capex&timeframe=3M&model_name=gpt-5-mini" -H "X-API-Key: YOUR_API_KEY"curl "https://eternal-agents.com/developers/monitoring/stability?regime_type=Liquidity%20Withdrawal%20Shock&asset=SPY&model_name=gpt-5-mini" -H "X-API-Key: YOUR_API_KEY"curl "https://eternal-agents.com/developers/scenarios/explore?scenario_type=inflation_reacceleration&assets=SPY,GLD,TLT¤t_regime=Goldilocks%20Expansion&model_name=gpt-5-mini" -H "X-API-Key: YOUR_API_KEY"curl "https://eternal-agents.com/developers/research/themes/deglobalization/analyze?specific_question=Which%20assets%20benefit%20if%20trade%20fragmentation%20accelerates%3F&model_name=gpt-5-mini" -H "X-API-Key: YOUR_API_KEY"Primary routes
https://eternal-agents.com/developers/llm-modelshttps://eternal-agents.com/developers/regimeshttps://eternal-agents.com/developers/regimes/{slug}https://eternal-agents.com/developers/compare/cross-assethttps://eternal-agents.com/developers/compare/divergencehttps://eternal-agents.com/developers/compare/actors/{actor_type}/assesshttps://eternal-agents.com/developers/narrative/impact-trailhttps://eternal-agents.com/developers/narrative/drifthttps://eternal-agents.com/developers/narrative/currenthttps://eternal-agents.com/developers/monitoring/stabilityhttps://eternal-agents.com/developers/monitoring/inflectionhttps://eternal-agents.com/developers/scenarios/explorehttps://eternal-agents.com/developers/scenarios/risk-factorshttps://eternal-agents.com/developers/scenarios/portfolio-overlayhttps://eternal-agents.com/developers/scenarios/customhttps://eternal-agents.com/developers/research/case-studies/{id}/deep-divehttps://eternal-agents.com/developers/research/themes/{id}/analyzehttps://eternal-agents.com/developers/api/v1/prices/{ticker}https://eternal-agents.com/developers/personal/watchlisthttps://eternal-agents.com/developers/personal/journalhttps://eternal-agents.com/developers/personal/timelineOpenAPI
The OpenAPI specification is the complete reference for schemas, parameters, responses, and errors. Use it when you want to generate a client, inspect an exact payload, or validate an integration endpoint by endpoint.