Research API reference

Create a key in the dashboard, send it with one request, and keep the returned request ID with your research log. The example asks for the public SEC filing chronology for Apple; it does not require a market-data license.

export DATACEDAR_API_KEY="dc_..."

curl --request GET \
  --url "https://api.datacedar.com/v3/stocks/AAPL/filings?form=10-Q&limit=5" \
  --header "X-API-Key: $DATACEDAR_API_KEY"

Use the production origin configured for your account. Local development reads the API origin from DATACEDAR_API_URL; the Next.js application proxies authenticated dashboard requests without becoming the data authority.

Send one key through X-API-Key or Authorization: Bearer. Do not send both. Account keys begin with dc_, are displayed once when created, and are stored as hashes by DataCedar.

# Header form
X-API-Key: dc_...

# Bearer form
Authorization: Bearer dc_...

Successful list responses return data, pagination, and meta. A stream may also include coverage or availability when the distinction between empty, missing, and restricted matters.

{
  "data": [{ "symbol": "AAPL", "form": "10-Q" }],
  "pagination": {
    "count": 1,
    "limit": 5,
    "has_more": false,
    "next_cursor": null
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-07-17T20:15:00Z",
    "schema_version": "v3"
  }
}

Unknown JSON fields may be added in a backwards-compatible release. Clients should ignore fields they do not recognize and must not rely on object key order.

List endpoints use opaque cursors. Pass the returned next_cursor unchanged into the next request. Do not parse it, synthesize it, or combine it with a different filter set.

GET /v3/stocks/AAPL/documents?limit=100
GET /v3/stocks/AAPL/documents?limit=100&cursor=eyJ...

# Continue until pagination.has_more is false.

Cursor ordering is deterministic for the same filters and eligible data snapshot. If an acquisition run adds newly eligible records during a long backfill, restart the export with a saved as-of cutoff when exact snapshot consistency is required.

DataCedar does not overload one timestamp. Depending on the stream, a record can carry economic-period, event, publication, filing, retrieval, market-session, and known-at times.

The catalog below is the customer-facing v3 market-research surface available today. Historical depth is reported per source and instrument rather than implied by route availability.

Market-bar source contract

Stock and crypto bars share a stable response envelope, but they do not pretend to be one consolidated feed. Every row identifies its native source, feed, timeframe, adjustment, and conservative known_at_ms.

# Discover live Binance Spot symbols
GET /v3/crypto/assets?q=BTC&status=TRADING&limit=100

# Yahoo daily history (raw or all-adjusted)
GET /v3/stocks/AAPL/bars?timeframe=1Day&adjustment=all&start=2000-01-01T00:00:00Z

# Binance one-minute history; use the returned cursor unchanged
GET /v3/crypto/BTCUSDT/bars?timeframe=1Min&start=2025-09-01T00:00:00Z&limit=5000

Default acquisition cadence

Cadence is configurable per deployment. These defaults describe how often the durable scheduler attempts each source; they are not a guarantee that a provider has published a new record.

The SSE route and webhook worker read the same event revisions, source-rights registry, history window, and plan latency as REST. Explorer is delayed 15 minutes, Quant five minutes, Desk Lite one minute, and Desk has realtime eligibility.

curl -N 'https://api.datacedar.com/v3/intelligence/stream?symbol=BTC' \
  -H 'X-API-Key: dc_...' \
  -H 'Accept: text/event-stream' \
  -H 'Last-Event-ID: <optional cursor>'

SSE emits intelligence.event and heartbeat events. Persist each SSE id and send it as Last-Event-ID after reconnecting. The server also sends transport keep-alives.

POST /v3/intelligence/subscriptions
{
  "delivery_kind": "webhook",
  "endpoint": "https://hooks.example.com/datacedar",
  "latency_class": "delayed",
  "filters": {
    "symbols": ["BTC", "AAPL"],
    "event_types": ["exchange_listing"],
    "source_ids": ["binance_announcements"]
  }
}

The create response returns signing_secret once. Verify DataCedar-Signature as HMAC-SHA256 over <unix timestamp>.<raw body>, reject stale timestamps, and deduplicate with Idempotency-Key. Redirects and private-network endpoints are rejected; repeated failures disable the subscription after ten attempts.

Active webhook quotas are Explorer 1, Quant 5, Desk Lite 25, and Desk 100. Concurrent SSE quotas are 1, 3, 10, and 25 respectively. SSE connections expire after five minutes and reconnect from Last-Event-ID.

Crypto bar WebSocket compatibility

/v1beta3/crypto/{location} streams only bars, updatedBars, and dailyBars. Tick trades, quotes, and orderbooks are not active datasets: their REST routes return 410 DATASET_NOT_ACTIVE and WebSocket subscriptions are rejected explicitly. The socket requires in-protocol authentication within ten seconds, consumes the account request bucket, and requires reauthentication every five minutes. Explorer/Quant/Desk Lite/Desk allow 1/2/5/10 connections and 5/25/100/500 bar channel-symbol subscriptions per connection; wildcard subscriptions are Desk-only.

Connect a Streamable HTTP client to https://api.datacedar.com/mcp. Add Authorization: Bearer dc_... to use the same account plan and history limits as REST.

{
  "mcpServers": {
    "datacedar": {
      "url": "https://api.datacedar.com/mcp",
      "headers": { "Authorization": "Bearer dc_..." }
    }
  }
}

The exact tool set is datacedar_search_events, datacedar_get_event, datacedar_search, datacedar_entity_timeline, datacedar_get_document, datacedar_get_cluster, datacedar_trends, datacedar_coverage, and datacedar_sources. Tool calls execute the REST handlers in-process; there is no looser MCP data path. An intentionally keyless call receives the bounded demo, while a supplied invalid, expired, or revoked key fails authentication rather than silently becoming demo access.

Error responses use a stable machine code, a human-readable message, optional field details, and the same request ID emitted to sanitized service logs.

{
  "error": {
    "code": "INVALID_SYMBOL",
    "message": "Symbol contains unsupported characters.",
    "details": { "field": "symbol" },
    "request_id": "req_..."
  }
}

Customer requests return sources explicitly enabled for public serving. Each market row keeps its source and feed; Binance is a venue-specific source, not a claim of consolidated crypto pricing.

GDELT is a discovery and link-metadata source. A body-only ticker match is archived for audit but does not become a public market event unless the headline supports the ticker or a deterministic company alias. Publisher article bodies are not redistributed.

Decodo may transport a brittle public request, but it does not grant copyright, exchange, database, storage, or redistribution rights. Acquisition adapters and serving entitlements are reviewed independently.

Inspect the live edge at DataCedar Status. Correction, attribution, removal, and source-suspension requests follow the documented data-rights and takedown workflow.

Plans change request throughput, market and intelligence history, event freshness, saved-view and delivery quotas, and crypto-stream concurrency. They do not unlock unlisted or internally held datasets. Current SEC evidence routes remain source- and rights-gated rather than being artificially hidden by a market-history window.

For batch work, page sequentially within each symbol, cap concurrency, cache immutable document responses, and retry only transient status codes. Contact us before designing a sustained workload near the Desk ceiling.

A reproducible result saves more than the response body. Record the request URL and filters, as-of cutoff, response request IDs, pagination cursors or export manifest, coverage state, schema version, source run IDs, and the code revision that produced the analysis.

Raw provider objects are content-addressed and written to Cloudflare R2 before normalization. They are recovery evidence, not an unfiltered public download tier. Customer-facing data still passes normalization, coverage, plan, and rights checks.