Endpoint#
POST /api/research
Runs one of the eleven operations: get_digest, get_signal_packet, export_signal_packet, search_stories, get_entity_timeline, find_records, get_record, get_observations, get_changes, export_records, list_watchlists. Requires a Professional credential with the api_access entitlement. Metered against the monthly allowance; an exhausted allowance returns 429 with Retry-After and X-RateLimit-* headers and never charges an overage.
Authentication#
[]An empty security requirement means this operation does not declare authentication. Read operation notes for entitlement and protocol-method requirements.
Parameters#
No parameters declared by the specification.
Request body#
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"operation",
"arguments"
],
"properties": {
"operation": {
"type": "string",
"enum": [
"get_digest",
"get_signal_packet",
"export_signal_packet",
"search_stories",
"get_entity_timeline",
"find_records",
"get_record",
"get_observations",
"get_changes",
"export_records",
"list_watchlists"
],
"description": "The research operation to run."
},
"arguments": {
"type": "object",
"description": "Operation arguments, validated against the operation's typed input schema.",
"oneOf": [
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"packet_id": {
"type": "string",
"maxLength": 180
}
},
"required": [],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"packet_id": {
"type": "string",
"maxLength": 180
},
"format": {
"type": "string",
"enum": [
"markdown",
"json"
]
}
},
"required": [
"format"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 180
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20
}
},
"required": [
"query"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"entity": {
"type": "string",
"maxLength": 120
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20
}
},
"required": [
"entity"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"dataset": {
"type": "string",
"enum": [
"documents",
"social",
"indicators"
],
"description": "Default documents."
},
"q": {
"type": "string",
"maxLength": 180,
"description": "Literal case-insensitive substring of title or publisher."
},
"source": {
"type": "string",
"maxLength": 180,
"description": "Exact publisher label."
},
"from": {
"type": "string",
"description": "Inclusive UTC collection day, YYYY-MM-DD (first_seen for documents, captured_at otherwise)."
},
"to": {
"type": "string",
"description": "Inclusive UTC collection day, YYYY-MM-DD."
},
"text": {
"type": "string",
"enum": [
"available"
],
"description": "Documents only: records with approved original text."
},
"mode": {
"type": "string",
"enum": [
"raw",
"release",
"topics"
],
"description": "raw (default) = one row per record or collection run; release = indicators only, one row per series and period; topics = social only, one row per (platform, topic) within the window (default 30 days, max 92)."
},
"watch": {
"type": "string",
"enum": [
"data-security",
"export-controls",
"property-support",
"semiconductors"
],
"description": "Reviewed topic filter (see list_watchlists): a title match on a listed bilingual term, nothing inferred."
},
"topic": {
"type": "string",
"enum": [
"data-security",
"export-controls",
"property-support",
"semiconductors"
],
"description": "Alias of watch."
},
"change_type": {
"type": "string",
"enum": [
"new",
"newly_discovered",
"revised"
],
"description": "Documents only: new, newly_discovered (published more than 2 days before we first saw it) or revised (a changed body was observed)."
},
"series": {
"type": "string",
"description": "Indicators only: exact series_id such as cpi-yoy."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page, with the same filters. Valid 24 hours."
},
"fields": {
"type": "string",
"description": "Comma-separated field keys; default all."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20
}
},
"required": [],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^(documents|social|indicators):[1-9][0-9]*$"
}
},
"required": [
"id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"series_id": {
"type": "string",
"pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
"maxLength": 120
},
"from": {
"type": "string",
"description": "Earliest reference period, YYYY-MM or YYYY-MM-DD."
},
"to": {
"type": "string",
"description": "Latest reference period, inclusive."
}
},
"required": [
"series_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"since": {
"type": "string",
"maxLength": 400,
"description": "ISO-8601 instant with timezone (inclusive), or a next_since token."
},
"cursor": {
"type": "string",
"maxLength": 400,
"description": "next_cursor from the previous call."
},
"watch": {
"type": "string",
"enum": [
"data-security",
"export-controls",
"property-support",
"semiconductors"
]
},
"topic": {
"type": "string",
"enum": [
"data-security",
"export-controls",
"property-support",
"semiconductors"
],
"description": "Alias of watch."
},
"source": {
"type": "string",
"maxLength": 180
},
"q": {
"type": "string",
"maxLength": 180
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20
}
},
"required": [],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"dataset": {
"type": "string",
"enum": [
"documents",
"social",
"indicators"
],
"description": "Default documents."
},
"q": {
"type": "string",
"maxLength": 180,
"description": "Literal case-insensitive substring of title or publisher."
},
"source": {
"type": "string",
"maxLength": 180,
"description": "Exact publisher label."
},
"from": {
"type": "string",
"description": "Inclusive UTC collection day, YYYY-MM-DD (first_seen for documents, captured_at otherwise)."
},
"to": {
"type": "string",
"description": "Inclusive UTC collection day, YYYY-MM-DD."
},
"text": {
"type": "string",
"enum": [
"available"
],
"description": "Documents only: records with approved original text."
},
"mode": {
"type": "string",
"enum": [
"raw",
"release",
"topics"
],
"description": "raw (default) = one row per record or collection run; release = indicators only, one row per series and period; topics = social only, one row per (platform, topic) within the window (default 30 days, max 92)."
},
"watch": {
"type": "string",
"enum": [
"data-security",
"export-controls",
"property-support",
"semiconductors"
],
"description": "Reviewed topic filter (see list_watchlists): a title match on a listed bilingual term, nothing inferred."
},
"topic": {
"type": "string",
"enum": [
"data-security",
"export-controls",
"property-support",
"semiconductors"
],
"description": "Alias of watch."
},
"change_type": {
"type": "string",
"enum": [
"new",
"newly_discovered",
"revised"
],
"description": "Documents only: new, newly_discovered (published more than 2 days before we first saw it) or revised (a changed body was observed)."
},
"series": {
"type": "string",
"description": "Indicators only: exact series_id such as cpi-yoy."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page, with the same filters. Valid 24 hours."
},
"fields": {
"type": "string",
"description": "Comma-separated field keys; default all."
},
"format": {
"type": "string",
"enum": [
"csv",
"json"
]
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"format"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}
]
}
}
}
}
}
}Responses and errors#
| HTTP status | Meaning |
|---|---|
| 200 | The operation result with usage metering. |
| 400 | Invalid request. JSON-RPC maps 400 to -32602. |
| 401 | Missing or invalid credential. JSON-RPC maps 401 to -32001. |
| 403 | Authenticated but not entitled. JSON-RPC maps 403 to -32003. |
| 404 | The requested resource or operation does not exist. JSON-RPC maps 404 to -32002. |
| 429 | Monthly allowance reached; no overage is charged. Retry after the calendar-month reset. Response carries RateLimit-* and X-RateLimit-* headers plus Retry-After. |
Response examples#
No response example is supplied by OpenAPI for this operation. The complete response schemas are preserved below; use an actual response for observed values.
Retry guidance#
See errors and retries. Honor operation-specific response headers. A POST may create state; do not replay it automatically.
Complete operation contract#
The expanded contract below includes all parameter constraints, response headers, schemas and examples from OpenAPI.
{
"path": "/api/research",
"method": "POST",
"parameters": [],
"operationId": "researchInvoke",
"summary": "Run one Professional research operation",
"description": "Runs one of the eleven operations: get_digest, get_signal_packet, export_signal_packet, search_stories, get_entity_timeline, find_records, get_record, get_observations, get_changes, export_records, list_watchlists. Requires a Professional credential with the api_access entitlement. Metered against the monthly allowance; an exhausted allowance returns 429 with Retry-After and X-RateLimit-* headers and never charges an overage.",
"tags": [
"research"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"operation",
"arguments"
],
"properties": {
"operation": {
"type": "string",
"enum": [
"get_digest",
"get_signal_packet",
"export_signal_packet",
"search_stories",
"get_entity_timeline",
"find_records",
"get_record",
"get_observations",
"get_changes",
"export_records",
"list_watchlists"
],
"description": "The research operation to run."
},
"arguments": {
"type": "object",
"description": "Operation arguments, validated against the operation's typed input schema.",
"oneOf": [
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"packet_id": {
"type": "string",
"maxLength": 180
}
},
"required": [],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"packet_id": {
"type": "string",
"maxLength": 180
},
"format": {
"type": "string",
"enum": [
"markdown",
"json"
]
}
},
"required": [
"format"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 180
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20
}
},
"required": [
"query"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"entity": {
"type": "string",
"maxLength": 120
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20
}
},
"required": [
"entity"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"dataset": {
"type": "string",
"enum": [
"documents",
"social",
"indicators"
],
"description": "Default documents."
},
"q": {
"type": "string",
"maxLength": 180,
"description": "Literal case-insensitive substring of title or publisher."
},
"source": {
"type": "string",
"maxLength": 180,
"description": "Exact publisher label."
},
"from": {
"type": "string",
"description": "Inclusive UTC collection day, YYYY-MM-DD (first_seen for documents, captured_at otherwise)."
},
"to": {
"type": "string",
"description": "Inclusive UTC collection day, YYYY-MM-DD."
},
"text": {
"type": "string",
"enum": [
"available"
],
"description": "Documents only: records with approved original text."
},
"mode": {
"type": "string",
"enum": [
"raw",
"release",
"topics"
],
"description": "raw (default) = one row per record or collection run; release = indicators only, one row per series and period; topics = social only, one row per (platform, topic) within the window (default 30 days, max 92)."
},
"watch": {
"type": "string",
"enum": [
"data-security",
"export-controls",
"property-support",
"semiconductors"
],
"description": "Reviewed topic filter (see list_watchlists): a title match on a listed bilingual term, nothing inferred."
},
"topic": {
"type": "string",
"enum": [
"data-security",
"export-controls",
"property-support",
"semiconductors"
],
"description": "Alias of watch."
},
"change_type": {
"type": "string",
"enum": [
"new",
"newly_discovered",
"revised"
],
"description": "Documents only: new, newly_discovered (published more than 2 days before we first saw it) or revised (a changed body was observed)."
},
"series": {
"type": "string",
"description": "Indicators only: exact series_id such as cpi-yoy."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page, with the same filters. Valid 24 hours."
},
"fields": {
"type": "string",
"description": "Comma-separated field keys; default all."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20
}
},
"required": [],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^(documents|social|indicators):[1-9][0-9]*$"
}
},
"required": [
"id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"series_id": {
"type": "string",
"pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
"maxLength": 120
},
"from": {
"type": "string",
"description": "Earliest reference period, YYYY-MM or YYYY-MM-DD."
},
"to": {
"type": "string",
"description": "Latest reference period, inclusive."
}
},
"required": [
"series_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"since": {
"type": "string",
"maxLength": 400,
"description": "ISO-8601 instant with timezone (inclusive), or a next_since token."
},
"cursor": {
"type": "string",
"maxLength": 400,
"description": "next_cursor from the previous call."
},
"watch": {
"type": "string",
"enum": [
"data-security",
"export-controls",
"property-support",
"semiconductors"
]
},
"topic": {
"type": "string",
"enum": [
"data-security",
"export-controls",
"property-support",
"semiconductors"
],
"description": "Alias of watch."
},
"source": {
"type": "string",
"maxLength": 180
},
"q": {
"type": "string",
"maxLength": 180
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20
}
},
"required": [],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"dataset": {
"type": "string",
"enum": [
"documents",
"social",
"indicators"
],
"description": "Default documents."
},
"q": {
"type": "string",
"maxLength": 180,
"description": "Literal case-insensitive substring of title or publisher."
},
"source": {
"type": "string",
"maxLength": 180,
"description": "Exact publisher label."
},
"from": {
"type": "string",
"description": "Inclusive UTC collection day, YYYY-MM-DD (first_seen for documents, captured_at otherwise)."
},
"to": {
"type": "string",
"description": "Inclusive UTC collection day, YYYY-MM-DD."
},
"text": {
"type": "string",
"enum": [
"available"
],
"description": "Documents only: records with approved original text."
},
"mode": {
"type": "string",
"enum": [
"raw",
"release",
"topics"
],
"description": "raw (default) = one row per record or collection run; release = indicators only, one row per series and period; topics = social only, one row per (platform, topic) within the window (default 30 days, max 92)."
},
"watch": {
"type": "string",
"enum": [
"data-security",
"export-controls",
"property-support",
"semiconductors"
],
"description": "Reviewed topic filter (see list_watchlists): a title match on a listed bilingual term, nothing inferred."
},
"topic": {
"type": "string",
"enum": [
"data-security",
"export-controls",
"property-support",
"semiconductors"
],
"description": "Alias of watch."
},
"change_type": {
"type": "string",
"enum": [
"new",
"newly_discovered",
"revised"
],
"description": "Documents only: new, newly_discovered (published more than 2 days before we first saw it) or revised (a changed body was observed)."
},
"series": {
"type": "string",
"description": "Indicators only: exact series_id such as cpi-yoy."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page, with the same filters. Valid 24 hours."
},
"fields": {
"type": "string",
"description": "Comma-separated field keys; default all."
},
"format": {
"type": "string",
"enum": [
"csv",
"json"
]
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"format"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "The operation result with usage metering.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"result": {
"type": "object",
"additionalProperties": true,
"description": "The operation's result object. Field shape varies by operation; each operation carries the honesty fields its tool description names (coverage, low_confidence, preview, belongs_to_current_edition, retained_last_known_good, and the limits thresholds for the search tools)."
},
"usage": {
"type": "object",
"properties": {
"used": {
"type": "integer"
},
"limit": {
"type": "integer"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid request. JSON-RPC maps 400 to -32602.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "A stable machine-readable code, e.g. unauthorized or not_found."
},
"message": {
"type": "string",
"description": "A human-readable explanation."
},
"hint": {
"type": "string",
"description": "Optional resolution pointer."
}
}
}
}
}
}
}
},
"401": {
"description": "Missing or invalid credential. JSON-RPC maps 401 to -32001.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "A stable machine-readable code, e.g. unauthorized or not_found."
},
"message": {
"type": "string",
"description": "A human-readable explanation."
},
"hint": {
"type": "string",
"description": "Optional resolution pointer."
}
}
}
}
}
}
}
},
"403": {
"description": "Authenticated but not entitled. JSON-RPC maps 403 to -32003.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "A stable machine-readable code, e.g. unauthorized or not_found."
},
"message": {
"type": "string",
"description": "A human-readable explanation."
},
"hint": {
"type": "string",
"description": "Optional resolution pointer."
}
}
}
}
}
}
}
},
"404": {
"description": "The requested resource or operation does not exist. JSON-RPC maps 404 to -32002.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "A stable machine-readable code, e.g. unauthorized or not_found."
},
"message": {
"type": "string",
"description": "A human-readable explanation."
},
"hint": {
"type": "string",
"description": "Optional resolution pointer."
}
}
}
}
}
}
}
},
"429": {
"description": "Monthly allowance reached; no overage is charged. Retry after the calendar-month reset. Response carries RateLimit-* and X-RateLimit-* headers plus Retry-After.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
},
"RateLimit-Limit": {
"schema": {
"type": "integer"
}
},
"RateLimit-Remaining": {
"schema": {
"type": "integer"
}
},
"RateLimit-Reset": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "A stable machine-readable code, e.g. unauthorized or not_found."
},
"message": {
"type": "string",
"description": "A human-readable explanation."
},
"hint": {
"type": "string",
"description": "Optional resolution pointer."
}
}
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "curl",
"label": "curl (Pro key)",
"source": "curl -s 'https://china-snapshot.com/api/research' \\\n -H \"Authorization: Bearer $CS_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n -d '{\"operation\":\"find_records\",\"arguments\":{\"q\":\"export\",\"limit\":3}}'"
}
]
}