Instruments
Normalized equity, ETF, and index security-master resources.
GET/v1/instruments/{instrument_id}Get a normalized equity, ETF, or index+
Parameters
instrument_idpathInstrumentIdRequired—Example: XSHG:600570
Responses
Instrument found
application/json · InstrumentResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource not found
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/instruments/XSHG:600570' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'Market Data
Cached quotes, bars, and best-effort streams.
GET/v1/market-data/barsQuery equity, ETF, or index OHLCV bars across complete timeframes+
Uses an inclusive `start` and exclusive `end`. JSON is the default. Send `Accept: application/x-ndjson` for one bar per line followed by a `stream_end` control record. Intraday bars are derived from upstream sampled cumulative quotes and are explicitly marked `snapshot_derived`; daily bars come from upstream OHLCV endpoints. Longer equity bars come from upstream period endpoints; longer ETF and index bars are aggregated from upstream daily bars and marked `daily_derived`.
Parameters
symbolsqueryInstrumentId[]RequiredComma-separated canonical IDs; tenant limits apply.Example: ["XSHG:600570","XSHE:000001"]
startquerystring<date-time>RequiredInclusive UTC timestamp.
endquerystring<date-time>RequiredExclusive UTC timestamp; tenant range limits apply.
timeframequeryBarTimeframeOptional—
adjustmentqueryraw | forward | backwardOptionalETF and index bars accept `raw` only.Example: raw
feedqueryauto | realtime | delayedOptionalDeprecatedCompatibility routing hint; the currently deployed source exposes one feed.Example: auto
sortqueryasc | descOptional—Example: asc
Responses
Bars or an NDJSON bar stream
application/json · BarsResponse / application/x-ndjson · BarStreamRecordInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource not found
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/market-data/bars?symbols=XSHG%3A600570%2CXSHE%3A000001&start=2026-07-01T00%3A00%3A00Z&end=2026-08-01T00%3A00%3A00Z' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'GET/v1/market-data/quotes/latestGet latest quotes for multiple equities, ETFs, or indexes+
Parameters
symbolsqueryInstrumentId[]RequiredComma-separated canonical IDs; tenant limits apply.Example: ["XSHG:600570","XSHE:000001"]
feedqueryauto | realtime | delayedOptionalDeprecatedCompatibility routing hint; the currently deployed source exposes one feed.Example: auto
Responses
Latest quotes
application/json · QuotesResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource not found
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/market-data/quotes/latest?symbols=XSHG%3A600570%2CXSHE%3A000001' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'GET/v1/market-data/streamStream best-effort latest quotes with SSE+
Emits `quote`, `heartbeat`, and `reconnect` events. This MVP deliberately provides neither durability nor replay. A new connection starts from the current quote. The regular OpenAPI HTTP operation describes both transports; a separate AsyncAPI contract is unnecessary for this unidirectional SSE API.
Parameters
symbolsqueryInstrumentId[]RequiredComma-separated canonical IDs; tenant limits apply.Example: ["XSHG:600570","XSHE:000001"]
feedqueryauto | realtime | delayedOptionalDeprecatedCompatibility routing hint; the currently deployed source exposes one feed.Example: auto
heartbeat_secondsqueryintegerOptional—Example: 20
Responses
SSE quote stream
text/event-stream · MarketEventInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource not found
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/market-data/stream?symbols=XSHG%3A600570%2CXSHE%3A000001' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'Agent Context
Agent-oriented compound views assembled from reusable cached resources.
GET/v1/agent/context/{instrument_id}Get a comprehensive cached context for one equity, ETF, or index+
Combines the company profile, latest quote, and requested bars in one agent-friendly response. The operation does not create a monolithic cache entry: it reuses canonical per-instrument quote and time-partitioned bar fragments, so overlapping requests from different users share cache hits. When `start` and `end` are both omitted, the service returns up to the last 365 calendar days, capped by the tenant's bar-range limit. Provider data is included verbatim beside normalized fields. Both dates must be supplied together when overriding the default range.
Parameters
instrument_idpathInstrumentIdRequired—Example: XSHG:600570
startquerystring<date-time>OptionalInclusive UTC timestamp; must be paired with `end`.
endquerystring<date-time>OptionalExclusive UTC timestamp; must be paired with `start`.
timeframequeryBarTimeframeOptional—
adjustmentqueryraw | forward | backwardOptionalETF and index bars accept `raw` only.Example: raw
sortqueryasc | descOptional—Example: asc
Responses
Agent context assembled from reusable cached resources
application/json · AgentContextResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource not found
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/agent/context/XSHG:600570' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'Aggregate Data
Nine agent-facing capability APIs covering all 371 published operations.
GET/v1/discoveryList exact discovery operation contracts+
Parameters
operationquerystringOptionalCase-sensitive operation name. Omit to list every operation in the capability.
Responses
Exact generated workbook contracts for the selected capability
application/json · OperationContractsResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/discovery' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'POST/v1/discoveryInvoke a discovery or screening operation+
Parameters
This operation has no parameters.
Request body
`operation` must be one of the operations assigned to this capability in the published operation catalog. `parameters` uses the exact contract field names. Enumeration parameters accept a dictionary code, caption, reference code, or canonical A-share ID; SparkData resolves and validates the upstream code.
application/json · AggregateQueryResponses
Complete upstream response plus resolved enum inputs and cache metadata
application/json · AggregateResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/discovery' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'GET/v1/entitiesList exact entity operation contracts+
Parameters
operationquerystringOptionalCase-sensitive operation name. Omit to list every operation in the capability.
Responses
Exact generated workbook contracts for the selected capability
application/json · OperationContractsResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/entities' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'POST/v1/entitiesInvoke an entity or reference-data operation+
Parameters
This operation has no parameters.
Request body
`operation` must be one of the operations assigned to this capability in the published operation catalog. `parameters` uses the exact contract field names. Enumeration parameters accept a dictionary code, caption, reference code, or canonical A-share ID; SparkData resolves and validates the upstream code.
application/json · AggregateQueryResponses
Complete upstream response plus resolved enum inputs and cache metadata
application/json · AggregateResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/entities' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'GET/v1/market-dataList exact market-data operation contracts+
Parameters
operationquerystringOptionalCase-sensitive operation name. Omit to list every operation in the capability.
Responses
Exact generated workbook contracts for the selected capability
application/json · OperationContractsResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/market-data' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'POST/v1/market-dataInvoke a unified market-data operation+
Parameters
This operation has no parameters.
Request body
`operation` must be one of the operations assigned to this capability in the published operation catalog. `parameters` uses the exact contract field names. Enumeration parameters accept a dictionary code, caption, reference code, or canonical A-share ID; SparkData resolves and validates the upstream code.
application/json · AggregateQueryResponses
Complete upstream response plus resolved enum inputs and cache metadata
application/json · AggregateResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/market-data' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'GET/v1/fundamentalsList exact fundamentals operation contracts+
Parameters
operationquerystringOptionalCase-sensitive operation name. Omit to list every operation in the capability.
Responses
Exact generated workbook contracts for the selected capability
application/json · OperationContractsResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/fundamentals' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'POST/v1/fundamentalsInvoke a fundamentals or forecast operation+
Parameters
This operation has no parameters.
Request body
`operation` must be one of the operations assigned to this capability in the published operation catalog. `parameters` uses the exact contract field names. Enumeration parameters accept a dictionary code, caption, reference code, or canonical A-share ID; SparkData resolves and validates the upstream code.
application/json · AggregateQueryResponses
Complete upstream response plus resolved enum inputs and cache metadata
application/json · AggregateResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/fundamentals' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'GET/v1/ownershipList exact ownership operation contracts+
Parameters
operationquerystringOptionalCase-sensitive operation name. Omit to list every operation in the capability.
Responses
Exact generated workbook contracts for the selected capability
application/json · OperationContractsResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/ownership' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'POST/v1/ownershipInvoke an ownership or portfolio operation+
Parameters
This operation has no parameters.
Request body
`operation` must be one of the operations assigned to this capability in the published operation catalog. `parameters` uses the exact contract field names. Enumeration parameters accept a dictionary code, caption, reference code, or canonical A-share ID; SparkData resolves and validates the upstream code.
application/json · AggregateQueryResponses
Complete upstream response plus resolved enum inputs and cache metadata
application/json · AggregateResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/ownership' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'GET/v1/eventsList exact event operation contracts+
Parameters
operationquerystringOptionalCase-sensitive operation name. Omit to list every operation in the capability.
Responses
Exact generated workbook contracts for the selected capability
application/json · OperationContractsResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/events' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'POST/v1/eventsInvoke an event, corporate-action, or risk operation+
Parameters
This operation has no parameters.
Request body
`operation` must be one of the operations assigned to this capability in the published operation catalog. `parameters` uses the exact contract field names. Enumeration parameters accept a dictionary code, caption, reference code, or canonical A-share ID; SparkData resolves and validates the upstream code.
application/json · AggregateQueryResponses
Complete upstream response plus resolved enum inputs and cache metadata
application/json · AggregateResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/events' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'GET/v1/analyticsList exact analytics operation contracts+
Parameters
operationquerystringOptionalCase-sensitive operation name. Omit to list every operation in the capability.
Responses
Exact generated workbook contracts for the selected capability
application/json · OperationContractsResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/analytics' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'POST/v1/analyticsInvoke an analytics, valuation, or ranking operation+
Parameters
This operation has no parameters.
Request body
`operation` must be one of the operations assigned to this capability in the published operation catalog. `parameters` uses the exact contract field names. Enumeration parameters accept a dictionary code, caption, reference code, or canonical A-share ID; SparkData resolves and validates the upstream code.
application/json · AggregateQueryResponses
Complete upstream response plus resolved enum inputs and cache metadata
application/json · AggregateResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/analytics' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'GET/v1/economyList exact economy operation contracts+
Parameters
operationquerystringOptionalCase-sensitive operation name. Omit to list every operation in the capability.
Responses
Exact generated workbook contracts for the selected capability
application/json · OperationContractsResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/economy' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'POST/v1/economyInvoke a macro, regional, or industry-economy operation+
Parameters
This operation has no parameters.
Request body
`operation` must be one of the operations assigned to this capability in the published operation catalog. `parameters` uses the exact contract field names. Enumeration parameters accept a dictionary code, caption, reference code, or canonical A-share ID; SparkData resolves and validates the upstream code.
application/json · AggregateQueryResponses
Complete upstream response plus resolved enum inputs and cache metadata
application/json · AggregateResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/economy' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'GET/v1/contentList exact content operation contracts+
Parameters
operationquerystringOptionalCase-sensitive operation name. Omit to list every operation in the capability.
Responses
Exact generated workbook contracts for the selected capability
application/json · OperationContractsResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/content' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'POST/v1/contentInvoke a research, filing, news, or policy operation+
Parameters
This operation has no parameters.
Request body
`operation` must be one of the operations assigned to this capability in the published operation catalog. `parameters` uses the exact contract field names. Enumeration parameters accept a dictionary code, caption, reference code, or canonical A-share ID; SparkData resolves and validates the upstream code.
application/json · AggregateQueryResponses
Complete upstream response plus resolved enum inputs and cache metadata
application/json · AggregateResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/content' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'Data Catalog
Stable dataset groups and observed readiness without inferred rights or watermarks.
GET/v1/datasetsList stable dataset groups covering all 371 operations+
Parameters
This operation has no parameters.
Responses
Dataset catalog
application/json · DatasetsResponseMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/datasets' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'GET/v1/datasets/{dataset_id}Return one dataset and its stable operation names+
Parameters
dataset_idpathcn-equity | funds | bonds | indices | classifications | wealth-products | hk-equity | us-equity | neeq | macro-research | announcements | news-policy | business-risk | smart-screeningRequired—
Responses
Dataset detail
application/json · DatasetDetailResponseMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource not found
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/datasets/cn-equity' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'GET/v1/data-readinessReturn observed readiness without inventing coverage, rights, or watermarks+
Parameters
This operation has no parameters.
Responses
Observed catalog readiness
application/json · DataReadinessResponseMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/data-readiness' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'Research
Published research templates and tenant experiment metadata; no hosted execution.
GET/v1/research/templatesList six evidence-oriented research template definitions+
Parameters
This operation has no parameters.
Responses
Published research templates
application/json · ResearchTemplatesResponseMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/research/templates' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'GET/v1/experiment-runsList tenant experiment metadata+
Parameters
This operation has no parameters.
Responses
Experiment records
application/json · ExperimentRunsResponseMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/experiment-runs' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'POST/v1/experiment-runsRecord a planned research or factor experiment without executing it+
Parameters
This operation has no parameters.
Request body
Required
application/json · CreateExperimentRunResponses
Experiment metadata created
application/json · ExperimentRunResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/experiment-runs' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'GET/v1/experiment-runs/{run_id}Get one tenant experiment record+
Parameters
run_idpathstring<uuid>Required—
Responses
Experiment metadata
application/json · ExperimentRunResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource not found
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/experiment-runs/RUN_ID' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'PATCH/v1/experiment-runs/{run_id}Apply a guarded status transition and optional result summary+
Parameters
run_idpathstring<uuid>Required—
Request body
Required
application/json · UpdateExperimentRunResponses
Experiment metadata updated
application/json · ExperimentRunResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource not found
application/problem+json · ProblemResource state prevents the operation
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request PATCH \
'https://spark-data.cn/v1/experiment-runs/RUN_ID' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'Factors
Tenant-scoped factor definitions and immutable versions; no computation.
GET/v1/factorsList tenant factor definitions+
Parameters
This operation has no parameters.
Responses
Factor definitions
application/json · FactorsResponseMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/factors' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'POST/v1/factorsCreate a tenant-unique factor definition without running computation+
Parameters
This operation has no parameters.
Request body
Required
application/json · CreateFactorDefinitionResponses
Factor definition created
application/json · FactorResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource state prevents the operation
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/factors' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'GET/v1/factors/{factor_id}Get one tenant factor definition+
Parameters
factor_idpathstring<uuid>Required—
Responses
Factor definition
application/json · FactorResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource not found
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/factors/FACTOR_ID' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'GET/v1/factors/{factor_id}/versionsList immutable versions for one factor+
Parameters
factor_idpathstring<uuid>Required—
Responses
Factor versions
application/json · FactorVersionsResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource not found
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/factors/FACTOR_ID/versions' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'POST/v1/factors/{factor_id}/versionsCreate the next immutable declaration version+
Parameters
factor_idpathstring<uuid>Required—
Request body
Required
application/json · CreateFactorVersionResponses
Factor version created
application/json · FactorVersionResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource not found
application/problem+json · ProblemTenant API-key rate limit exceeded
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/factors/FACTOR_ID/versions' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'Online Agent
A2A 1.0 discovery, messages, Tasks, public workflow events, and cancellation.
GET/.well-known/agent-card.jsonDiscover the SparkData online research Agent+
Parameters
This operation has no parameters.
Responses
Public A2A Agent Card
application/json · AgentCardcurl --request GET \
'https://spark-data.cn/.well-known/agent-card.json'POST/v1/agent/a2a/message:sendSend one message and wait for the authoritative Task result+
Parameters
A2A-VersionheaderstringRequiredThis interface supports A2A protocol version 1.0 only.
A2A-ExtensionsheaderstringOptionalComma-separated optional A2A extension URIs selected by the client.
X-CSRF-TokenheaderstringRequiredToken returned by login or GET /v1/me; Origin must also exactly match an allowed production origin.
Request body
Required
application/a2a+json · SendAgentMessageRequestResponses
Completed or failed Task envelope
application/a2a+json · SendAgentMessageResponseInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource state prevents the operation
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/agent/a2a/message:send' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'POST/v1/agent/a2a/message:streamSend one message and stream Task lifecycle events+
The first SSE data field is a Task envelope. Later fields contain statusUpdate or artifactUpdate. Public workflow steps are not private model reasoning.
Parameters
A2A-VersionheaderstringRequiredThis interface supports A2A protocol version 1.0 only.
A2A-ExtensionsheaderstringOptionalComma-separated optional A2A extension URIs selected by the client.
X-CSRF-TokenheaderstringRequiredToken returned by login or GET /v1/me; Origin must also exactly match an allowed production origin.
Request body
Required
application/a2a+json · SendAgentMessageRequestResponses
Ordered A2A SSE events ending at a terminal Task state
text/event-stream · stringInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource state prevents the operation
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/agent/a2a/message:stream' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'GET/v1/agent/a2a/tasksList Tasks owned by the authenticated tenant user+
Parameters
A2A-VersionheaderstringRequiredThis interface supports A2A protocol version 1.0 only.
contextIdquerystring<uuid>Optional—
pageSizequeryintegerOptional—Example: 50
Responses
Owner-scoped Task page
application/a2a+json · AgentTaskListInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/agent/a2a/tasks' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'GET/v1/agent/a2a/tasks/{id}Get one authoritative owner-scoped Task snapshot+
Parameters
A2A-VersionheaderstringRequiredThis interface supports A2A protocol version 1.0 only.
idpathstring<uuid>Required—
Responses
Current Task snapshot
application/a2a+json · AgentTaskInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemResource not found
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request GET \
'https://spark-data.cn/v1/agent/a2a/tasks/value' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'POST/v1/agent/a2a/tasks/{id}:subscribeStream updates for one non-terminal owner-scoped Task+
Parameters
A2A-VersionheaderstringRequiredThis interface supports A2A protocol version 1.0 only.
A2A-ExtensionsheaderstringOptionalComma-separated optional A2A extension URIs selected by the client.
X-CSRF-TokenheaderstringRequiredToken returned by login or GET /v1/me; Origin must also exactly match an allowed production origin.
idpathstring<uuid>Required—
Responses
Current Task followed by ordered SSE updates
text/event-stream · stringInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource not found
application/problem+json · ProblemResource state prevents the operation
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/agent/a2a/tasks/value:subscribe' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY'POST/v1/agent/a2a/tasks/{id}:cancelCancel one non-terminal owner-scoped Task+
Parameters
A2A-VersionheaderstringRequiredThis interface supports A2A protocol version 1.0 only.
X-CSRF-TokenheaderstringRequiredToken returned by login or GET /v1/me; Origin must also exactly match an allowed production origin.
idpathstring<uuid>Required—
Request body
Optional
application/a2a+json · objectResponses
Canceled Task snapshot
application/a2a+json · AgentTaskInvalid request
application/problem+json · ProblemMissing, malformed, expired, revoked, or unknown API key
application/problem+json · ProblemAPI key lacks the required scope
application/problem+json · ProblemResource not found
application/problem+json · ProblemResource state prevents the operation
application/problem+json · ProblemMySQL, Redis, or upstream dependency is unavailable
application/problem+json · Problemcurl --request POST \
'https://spark-data.cn/v1/agent/a2a/tasks/value:cancel' \
--header 'Authorization: Bearer $SPARKDATA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"operation":"operation_code","params":{}}'Public data objects
Only objects used by customer-facing endpoints are listed. Expand one to inspect its fields, types, and requirements.
AgentCardobject+
namestringRequireddescriptionstringRequiredsupportedInterfacesobject[]RequiredversionstringRequiredcapabilitiesobjectRequireddefaultInputModesstring[]RequireddefaultOutputModesstring[]Requiredskillsobject[]RequiredSendAgentMessageRequestobject+
messageAgentMessageRequiredconfigurationAgentSendConfigurationOptionalSendAgentMessageResponseobject+
taskAgentTaskRequiredAgentSendConfigurationobject+
acceptedOutputModestext/markdown | application/json[]OptionalhistoryLengthintegerOptionalAgentMessageobject+
messageIdstring<uuid>RequiredroleROLE_USER | ROLE_AGENTRequiredpartsAgentPart[]RequiredcontextIdstring<uuid>OptionaltaskIdstring<uuid>OptionalAgentPartobject | object+
AgentTaskStateTASK_STATE_SUBMITTED | TASK_STATE_WORKING | TASK_STATE_COMPLETED | TASK_STATE_FAILED | TASK_STATE_CANCELED+
AgentTaskStatusobject+
stateAgentTaskStateRequiredtimestampstring<date-time>RequiredmessageAgentMessageOptionalAgentArtifactobject+
artifactIdstringRequirednamestringRequiredpartsAgentPart[]Requiredextensionsstring<uri>[]OptionalmetadataobjectOptionalAgentTaskobject+
idstring<uuid>RequiredcontextIdstring<uuid>RequiredstatusAgentTaskStatusRequiredartifactsAgentArtifact[]OptionalhistoryAgentMessage[]OptionalmetadataobjectRequiredAgentTaskListobject+
tasksAgentTask[]RequirednextPageTokenstringOptionalIdentityProvideremail | phone | wechat+
DatasetDefinitionobject+
dataset_idstringRequirednamestringRequireddescriptionstringRequiredmarketsstring[]Requiredasset_classesstring[]Requiredoperation_countintegerRequiredcapabilitiesCapability[]Requirednormalizationmixed | provider_envelopeRequiredrights_statusstringRequiredfreshnessstringRequiredcontract_versionstringRequiredDatasetDetailobject+
DatasetReadinessobject+
dataset_idstringRequiredcontract_statusstringRequireddelivery_statusstringRequiredcoverage_statusstringRequiredrights_statusstringRequiredwatermarknull | stringRequiredoperation_countintegerRequiredobserved_atstring<date-time>RequiredResearchTemplateobject+
template_idstringRequiredversionstringRequirednamestringRequireddescriptionstringRequiredrequired_datasetsstring[]Requiredrequired_capabilitiesCapability[]Requiredoutput_formatsapplication/json | text/markdown | text/html[]Requiredevidence_requiredbooleanRequiredrisk_noticestringRequiredFactorDefinitionobject+
idstring<uuid>Requiredtenant_idstring<uuid>RequirednamestringRequireddescriptionstringRequiredinput_datasetsstring[]Requireduniverse_rulestringRequiredcreated_atstring<date-time>RequiredCreateFactorDefinitionobject+
namestringRequireddescriptionstringOptionalinput_datasetsstring[]Requireduniverse_rulestringRequiredFactorVersionobject+
idstring<uuid>Requiredfactor_idstring<uuid>Requiredversion_numberintegerRequiredexpressionstringRequiredlookback_daysintegerRequiredadjustmentraw | forward | backwardRequiredcreated_atstring<date-time>RequiredCreateFactorVersionobject+
expressionstringRequiredlookback_daysintegerRequiredadjustmentraw | forward | backwardOptionalExperimentKindresearch | factor+
ExperimentStatusplanned | running | succeeded | failed | cancelled+
ExperimentRunobject+
idstring<uuid>Requiredtenant_idstring<uuid>RequiredkindExperimentKindRequirednamestringRequiredfactor_version_idstring | nullRequiredresearch_template_idstring | nullRequiredinputsobjectRequiredcode_refstring | nullRequireddata_manifest_refstring | nullRequiredenvironmentobjectRequiredstatusExperimentStatusRequiredresultobjectRequiredcreated_atstring<date-time>Requiredupdated_atstring<date-time>RequiredCreateExperimentRunobject+
kindExperimentKindRequirednamestringRequiredfactor_version_idstring | nullOptionalresearch_template_idstring | nullOptionalinputsobjectOptionalcode_refstring | nullOptionaldata_manifest_refstring | nullOptionalenvironmentobjectOptionalUpdateExperimentRunobject+
statusExperimentStatusRequiredresultobjectOptionalInstrumentIdstring+
Canonical MIC-prefixed ID for a supported mainland equity, ETF, or index.
Decimalstring+
BarTimeframe1m | 5m | 15m | 30m | 1h | 1d | 1w | 1mo | 1q | 1y+
CacheStatushit | miss | mixed | bypass+
ResponseMetaobject+
request_idstring<uuid>Requiredschema_versionstringRequiredcache_statusCacheStatusRequiredsourcesparkdata-market-data | sparkdata-control-planeRequiredgenerated_atstring<date-time>RequiredInstrumentobject+
instrument_idInstrumentIdRequired · Canonical MIC-prefixed ID for a supported mainland equity, ETF, or index.symbolstringRequirednamestring | nullRequiredcompany_namestring | nullRequiredmicXSHG | XSHE | XBSERequiredasset_classequity | etf | indexRequiredcurrencystringRequiredtimezonestringRequiredstatusstringRequiredindustrystring | nullRequiredconceptsstring[]Requiredprovider_dataProviderDataRequiredProviderDataobject+
operationstringRequired · Exact operation name from the published source contract or dictionary service.rawobjectRequired · Exact untrimmed upstream envelope, row, or rows used for a derived record.Capabilitydiscovery | entities | market_data | fundamentals | ownership | events | analytics | economy | content+
ContractDataTypestring | string_array | number | number_array | date | date_array+
InputContractobject+
namestringRequired · Public parameter name accepted by SparkData.upstream_namestringRequired · Exact field name sent to the live upstream.display_namestringRequireddata_typeContractDataTypeRequireddescriptionstringRequiredrequiredbooleanRequiredenum_groupstring | nullRequired · Live dictionary group when the workbook marks the input as enumerated.enum_declarationstring | nullRequired · Unmodified enumeration declaration from the workbook.fixed_valuestring | nullRequired · Value marked as fixed by the workbook and inserted by SparkData.OutputContractobject+
namestringRequireddisplay_namestringRequireddata_typeContractDataTypeRequireddescriptionstringRequiredOperationContractobject+
api_idintegerRequiredsheet_namestringRequireddisplay_namestringRequiredoperationstringRequireddescriptionstringRequiredmethodstringRequiredpathstringRequiredcapabilityCapabilityRequiredlast_modifiedstringRequiredinputsInputContract[]RequiredoutputsOutputContract[]RequiredOperationContractsResponseobject+
metaResponseMetaRequireddataOperationContract[]RequiredAggregateQueryobject+
operationstringRequired · Case-sensitive Excel operation name, for example FinancialStatement.parametersobjectOptional · Exact Excel input names and values; undeclared fields are rejected.EnumResolutionobject+
fieldstringRequiredgroup_namestringRequiredinputobjectRequiredcodestringRequiredcaptionstring | nullRequiredprovider_dataProviderDataRequiredAggregateDataobject+
api_idintegerRequiredcapabilityCapabilityRequiredoperationstringRequiredresolved_parametersobjectRequired · Exact request sent upstream after fixed-value insertion and enum resolution.enum_resolutionsEnumResolution[]Requiredprovider_dataProviderDataRequiredAggregateResponseobject+
metaResponseMetaRequireddataAggregateDataRequiredPriceLevelobject+
priceDecimalRequiredsizeDecimalRequiredQuoteobject+
instrument_idInstrumentIdRequired · Canonical MIC-prefixed ID for a supported mainland equity, ETF, or index.event_timestring<date-time>Requiredlast_priceDecimalRequiredprevious_closeDecimalRequiredopenDecimalRequiredhighDecimalRequiredlowDecimalRequiredchangeDecimal | nullRequiredchange_percentDecimal | nullRequiredvolumeDecimalRequiredturnoverDecimalRequiredtrade_statusstringRequiredbid_levelsPriceLevel[]Requiredask_levelsPriceLevel[]Requiredprovider_dataProviderDataRequiredBarobject+
instrument_idInstrumentIdRequired · Canonical MIC-prefixed ID for a supported mainland equity, ETF, or index.event_timestring<date-time>Required · Start of the interval in UTC.trading_datestring | nullRequired · Upstream trading or period-end date; null for derived intraday bars.timeframeBarTimeframeRequiredopenDecimalRequiredhighDecimalRequiredlowDecimalRequiredcloseDecimalRequiredprevious_closeDecimal | nullRequiredvolumeDecimalRequiredturnoverDecimal | nullRequiredtrade_countinteger | nullRequiredsuspendedbooleanRequiredadjustmentraw | forward | backwardRequired · ETF and index bars accept `raw` only.aggregation_sourceprovider | snapshot_derived | daily_derivedRequiredprovider_dataProviderDataRequiredStreamControlobject+
control_typestream_end | heartbeat | reconnectRequiredrequest_idstring<uuid>Requiredevent_timestring<date-time>Requiredrecords_sentintegerOptionalMarketEventQuote | StreamControl+
BarStreamRecordBar | StreamControl+
AgentContextobject+
instrument_idInstrumentIdRequired · Canonical MIC-prefixed ID for a supported mainland equity, ETF, or index.instrumentInstrumentRequiredlatest_quoteQuote | nullRequiredbarsBar[]Requiredupstream_operationsstring[]RequiredAgentContextResponseobject+
metaResponseMetaRequireddataAgentContextRequiredDatasetsResponseobject+
metaResponseMetaRequireddataDatasetDefinition[]RequiredDatasetDetailResponseobject+
metaResponseMetaRequireddataDatasetDetailRequiredDataReadinessResponseobject+
metaResponseMetaRequireddataDatasetReadiness[]RequiredResearchTemplatesResponseobject+
metaResponseMetaRequireddataResearchTemplate[]RequiredFactorResponseobject+
metaResponseMetaRequireddataFactorDefinitionRequiredFactorsResponseobject+
metaResponseMetaRequireddataFactorDefinition[]RequiredFactorVersionResponseobject+
metaResponseMetaRequireddataFactorVersionRequiredFactorVersionsResponseobject+
metaResponseMetaRequireddataFactorVersion[]RequiredExperimentRunResponseobject+
metaResponseMetaRequireddataExperimentRunRequiredExperimentRunsResponseobject+
metaResponseMetaRequireddataExperimentRun[]RequiredInstrumentResponseobject+
metaResponseMetaRequireddataInstrumentRequiredInstrumentResponseObjectobject+
metaResponseMetaRequireddataInstrumentRequiredBarsResponseobject+
metaResponseMetaRequireddataBar[]RequiredQuotesResponseobject+
metaResponseMetaRequireddataQuote[]RequiredMeResponseobject+
metaResponseMetaRequireddataobjectRequiredInvalidParameterobject+
namestringRequiredreasonstringRequiredProblemobject+
typestring<uri-reference>RequiredtitlestringRequiredstatusintegerRequireddetailstringRequiredrequest_idstring<uuid>RequiredcodestringRequiredinvalid_parametersInvalidParameter[]Required