HTTP interfaces and versioning

Version and transport

The API exposes /v1 resources using UTF-8 JSON. Resource identifiers are opaque within their type. Date-time fields use offset-bearing timestamps; examples normalize to UTC. Monetary amounts use integer strings plus an asset and scale. Forecast estimates use finite numeric values with declared units.

Set SEER_API_BASE_URL to the service URL assigned to your connection and authenticate with its issued bearer token. The OpenAPI document defines the core resource schemas. Access also requires the relevant scopes, workspace membership and resource permissions.

Endpoints: Discovery and research

Query parameters and full payload definitions are in the downloadable OpenAPI. Tool invocation additionally enforces the selected manifest’s scopes.

Endpoints: Computation and monitoring

Query parameters and full payload definitions are in the downloadable OpenAPI. Tool invocation additionally enforces the selected manifest’s scopes.

Endpoints: Accounts and execution

Query parameters and full payload definitions are in the downloadable OpenAPI. Tool invocation additionally enforces the selected manifest’s scopes.

Invoke a tool

# Set SEER_API_BASE_URL and SEER_ACCESS_TOKEN from your connection settings.
curl --fail-with-body "${SEER_API_BASE_URL}/v1/tool-invocations" \
  -H "Authorization: Bearer ${SEER_ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-research-001' \
  --data '{
    "agent_revision_id": "agr_example_3",
    "tool": "market.bars",
    "input": {"instrumentId": "equity:listing:apple-common-xnas"}
  }'

Identity and pagination

The authenticated connection establishes principal and workspace. Agent revisions, jobs, accounts and artifacts are resolved within that authorization context. A request-body field cannot select a more privileged workspace.

List responses contain items, next_cursor and schema_version. Each opaque cursor binds its filters, sort order and authorization context. A null cursor denotes completion; an empty page with a non-null cursor denotes a traversal that still has remaining candidates after entitlement or time filtering.

Idempotency contract

Creation requests require Idempotency-Key. The binding is scoped by workspace, authenticated client, HTTP method, normalized resource path and key. Admission atomically associates this identity with the canonical payload fingerprint and resulting resource. The same identity and payload resolves to the original resource; a changed payload returns 409 IDEMPOTENCY_CONFLICT.

The connection policy defines the binding’s retention window. While that binding is active, a client recovering from a lost response repeats the original key and payload. Venue-level deduplication remains a separate property of the execution connection, so API idempotency and external execution identity have distinct records.

Compatibility

Compatibility is defined by both representation and meaning. Optional metadata can evolve without changing existing semantics. A change to units, financial authority, a required field or a state’s meaning is a breaking change.

The HTTP major version, tool schema revision and numerical-method revision identify separate compatibility boundaries. A client can therefore keep a stable transport integration while explicitly selecting a revised calculation. Unknown non-critical metadata is forward-compatible; unknown execution states and authority requirements remain uninterpreted until the client supports them.

Following asynchronous work

A synchronous tool invocation returns 200 with its result. A computation admitted for background work returns 202 with job_id and status_url. GET on the job returns accepted, running or waiting while work remains active, then completed with result_ref, failed with error_code, or cancelled.

For a completed job, GET /v1/artifacts/{artifact_id} retrieves the artifact identified by result_ref. The envelope declares kind and schema_revision; its data contains the corresponding forecast, portfolio proposal or tool result. Artifact lookup enforces the same workspace and resource access as job lookup. A completed job and an artifact’s financial meaning remain separate: a portfolio artifact is a proposal, not an executed position.

Accepted job response

202 Accepted from POST /v1/forecasts. The status URL is relative to the connection’s service base.

{
  "job_id": "job_example_1",
  "state": "accepted",
  "status_url": "/v1/jobs/job_example_1"
}

Completed job response

GET /v1/jobs/job_example_1 after computation finishes. result_ref is the artifact identifier used for retrieval.

{
  "job_id": "job_example_1",
  "state": "completed",
  "result_ref": "artifact_forecast_example_1"
}

Response and resource semantics

Completed tool response

200 OK for a market.bars request with start=2026-10-01, end=2026-10-02, interval=1d and adjustment=split_only. The two observations cover that illustrative request, not enough history for every indicator.

{
  "schema_version": "1.0",
  "invocation_id": "inv_example_1",
  "tool": "market.bars",
  "status": "complete",
  "data": {
    "instrumentId": "equity:listing:apple-common-xnas",
    "currency": "USD",
    "interval": "1d",
    "observations": [
      {
        "session": "2026-10-01",
        "close": "100.00"
      },
      {
        "session": "2026-10-02",
        "close": "102.00"
      }
    ],
    "adjustment": "split_only",
    "calendar": "XNAS"
  },
  "evidence": [
    {
      "id": "ev_prices_example",
      "revision": "1",
      "source_ref": "source_market_example"
    }
  ],
  "warnings": [],
  "next_cursor": null,
  "coverage": {
    "requested_start": "2026-10-01T00:00:00Z",
    "requested_end": "2026-10-02T23:59:59Z",
    "as_of": "2026-10-03T00:00:00Z",
    "source_refs": [
      "source_market_example"
    ],
    "missing_reasons": [],
    "revision_history": "complete"
  }
}

Retrieved forecast artifact

GET /v1/artifacts/artifact_forecast_example_1 resolves the completed job above. kind and schema_revision identify the payload contract; data preserves the original forecast identity.

{
  "artifact_id": "artifact_forecast_example_1",
  "kind": "forecast",
  "schema_revision": "1.0",
  "data": {
    "forecast_id": "fc_example_1",
    "instrument_id": "equity:listing:apple-common-xnas",
    "origin_at": "2026-10-01T20:05:00Z",
    "target": "simple_price_return",
    "horizon": {
      "value": 5,
      "unit": "trading_sessions"
    },
    "unit": "fraction",
    "model_revision": "aura-example-r1",
    "evidence_snapshot_id": "snap_example_1",
    "estimate": {
      "mean": 0.0218,
      "quantiles": {
        "0.05": -0.035438,
        "0.50": 0.015574,
        "0.95": 0.101898
      }
    },
    "evaluation_state": "pending_outcome"
  }
}

Standards used

Authentication lifecycle

An issued credential is bound to a client, workspace, intended audience, expiry and scope set. GET /v1/connection returns this effective context and operational limits without returning the secret. The response also supplies the default agent revision and MCP endpoint.

Create, rotate and revoke credentials in connection settings. Rotation can overlap two explicitly issued credentials; clients switch to the new credential before retiring the old one. Expired or revoked credentials return 401. A valid credential lacking a required grant returns 403. Financial authorizations are independently revocable and never implied by a replacement access token.

Limits, deadlines and idempotency retention

GET /v1/connection exposes request_limit_per_minute, max_concurrent_jobs, max_request_bytes, idempotency_retention_seconds, cursor_ttl_seconds and event_retention_seconds. These values describe the current connection policy, not hard-coded universal quotas. Service budgets and data entitlements are additional admission checks.

A creation response includes Idempotency-Key-Expires-At in UTC and X-Request-Id for support correlation. The binding starts at first durable admission. A timeout before a response is recovered with the original key and payload. Clients stop automatic replay before the known expiry; once the identity cannot be recovered safely, financial requests require resource reconciliation. HTTP client timeout does not cancel admitted work.

429 and retryable 503 responses include Retry-After as delta-seconds or an HTTP date. Poll no faster than the server’s supplied delay. Use a local elapsed-time budget and retain the job ID when that budget expires.

Where resource references originate

Stable pagination and resumption

GET collection requests accept limit from 1 to 100, default 20, and an opaque cursor. Preserve the original filters while advancing next_cursor. Collection traversal binds the source snapshot or upper watermark established on its first page; additions after that watermark appear in a new traversal. Cursor expiry returns 410 CURSOR_EXPIRED. Restart the query and deduplicate by stable resource ID rather than concatenating both traversals blindly.

Tool-result cursors are passed back in that tool’s input cursor field, not as an HTTP collection parameter. They preserve the original source query and its coverage. A new page is a new invocation with a new idempotency key. Retrying the same page keeps its existing key.

First successful call

HTTP response headers

All resource responses include X-Request-Id. Creation responses include Idempotency-Key-Expires-At, including retrieval of an already-admitted request. 401 includes WWW-Authenticate: Bearer. A retryable 429 or 503 includes Retry-After, interpreted as a minimum delay; polling responses can also supply it.

Collection query parameters and creation payloads are validated against OpenAPI. Unknown input fields are rejected. Unknown non-critical response metadata can be ignored, but clients stop rather than guess about an unsupported state, artifact kind or financial action type.