Developer documentation API v1
Integrate your first agent
Discover the connection, select an instrument and retrieve a structured result.
Create a scoped connection
In your workspace connection settings, create an integration connection, select its agent revision and grant research scopes. Copy the assigned HTTP base URL and issued access token into server-side environment variables. Keep the token out of browser bundles, notebooks committed to source control and model prompts.
For the first call, grant connection:read, agents:read, instruments:read, tools:read, tools:invoke, market:read, jobs:read and artifacts:read. Enable market.bars on the selected revision and its underlying data entitlement. No account or execution scope is needed.
Connection values
| Value | Where it comes from | How it is used |
|---|---|---|
| SEER_API_BASE_URL | Connection settings; HTTPS base without /v1. | Prefix for documented REST paths. |
| SEER_ACCESS_TOKEN | Issued connection credential. | Authorization: Bearer header. |
| agent_revision_id | GET /v1/connection → default_agent_revision_id, or GET /v1/agent-revisions. | Pins instructions and selected tool versions. |
| instrument_id | GET /v1/instruments with query, venue and kind filters. | Select the intended listing, not merely the issuer. |
| tool revision | GET /v1/tools. | Must match the revision pinned by the agent. |
Run the first research request
Download seer_client.py below, set the two connection variables and run with Python 3.10 or newer. It retrieves Apple’s XNAS equity listing and daily history; it never submits a financial action.
python3 seer_client.pyWhat the client does
The client reads /v1/connection, verifies the required scopes and retrieves the selected agent revision. It follows tool and instrument cursors, checks that market.bars is enabled at the pinned revision and requires exactly one matching equity listing on XNAS. It then invokes the tool with a new idempotency key.
A 200 response contains ToolResult. For 202, the client polls the returned same-service job path with a bounded deadline, retrieves the completed artifact and extracts its tool_result. A failed or cancelled job is explicit. A polling deadline leaves the job running; the client prints its durable ID for recovery.
Inspect the useful result
Illustrative client summary. Actual observation count follows the enabled history contract and current source coverage. Inspect the returned data and evidence before applying an indicator.
{
"tool": "market.bars",
"status": "complete",
"instrument_id": "equity:listing:apple-common-xnas",
"observation_count": 2,
"evidence_count": 1,
"warnings": []
}Resolve the first failure
| Response | Action |
|---|---|
| 401 | Replace or renew the issued credential in connection settings; do not loop on the rejected token. |
| 403 | Check effective scopes, source entitlement and the selected agent’s tool grants. |
| No unique listing | Use the discovery response to choose the intended security and venue. |
| 422 | Read the stable error code and correct the coverage or analytical prerequisite. |
| 429 | Honor Retry-After and the connection’s limits. |
| Lost POST response | Reuse the saved key and identical payload within its retention window; do not invent a replacement operation. |