Endpoint#
POST /api/alerts
Needs at least one of watch, q or source. channel=email (default) always delivers to the key's own address. channel=webhook takes an https webhook_url on a public host; the response carries webhook_secret once, and every POST is signed: X-China-Snapshot-Signature is the hex HMAC-SHA256 of "<X-China-Snapshot-Timestamp>.<raw body>". The alert starts from now.
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",
"properties": {
"label": {
"type": "string",
"maxLength": 80
},
"watch": {
"type": "string"
},
"q": {
"type": "string",
"minLength": 2,
"maxLength": 120
},
"source": {
"type": "string",
"maxLength": 80
},
"channel": {
"type": "string",
"enum": [
"email",
"webhook"
],
"default": "email"
},
"webhook_url": {
"type": "string",
"format": "uri",
"maxLength": 500
}
}
}
}
}
}Responses and errors#
| HTTP status | Meaning |
|---|---|
| 201 | Created; webhook_secret is present once for a webhook alert. |
| 400 | The alert is not acceptable (code invalid_parameter); the error says why. |
| 401 | Unknown, revoked or malformed key (code unauthorized). |
| 402 | Not a paid key, or the plan holds no more alerts (code plan_required). |
| 429 | Rate limit exceeded; honour Retry-After. |
| 503 | Alerts are not yet enabled on this deployment (migration 048 pending). |
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/alerts",
"method": "POST",
"parameters": [],
"operationId": "createAlert",
"summary": "Save an alert on the change feed",
"description": "Needs at least one of watch, q or source. channel=email (default) always delivers to the key's own address. channel=webhook takes an https webhook_url on a public host; the response carries webhook_secret once, and every POST is signed: X-China-Snapshot-Signature is the hex HMAC-SHA256 of \"<X-China-Snapshot-Timestamp>.<raw body>\". The alert starts from now.",
"tags": [
"keys",
"Retrieve changes",
"Manage access"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"label": {
"type": "string",
"maxLength": 80
},
"watch": {
"type": "string"
},
"q": {
"type": "string",
"minLength": 2,
"maxLength": 120
},
"source": {
"type": "string",
"maxLength": 80
},
"channel": {
"type": "string",
"enum": [
"email",
"webhook"
],
"default": "email"
},
"webhook_url": {
"type": "string",
"format": "uri",
"maxLength": 500
}
}
}
}
}
},
"responses": {
"201": {
"description": "Created; webhook_secret is present once for a webhook alert.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"alert"
],
"properties": {
"alert": {
"type": "object",
"required": [
"id",
"channel",
"target",
"active"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"label": {
"type": [
"string",
"null"
]
},
"watch": {
"type": [
"string",
"null"
],
"description": "A watchlist slug (list_watchlists)."
},
"q": {
"type": [
"string",
"null"
]
},
"source": {
"type": [
"string",
"null"
]
},
"channel": {
"type": "string",
"enum": [
"email",
"webhook"
]
},
"target": {
"type": "string",
"description": "The key's own email, or the https webhook URL."
},
"active": {
"type": "boolean"
},
"last_delivered_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_error": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
},
"webhook_secret": {
"type": "string"
}
}
}
}
}
},
"400": {
"description": "The alert is not acceptable (code invalid_parameter); the error says why."
},
"401": {
"description": "Unknown, revoked or malformed key (code unauthorized)."
},
"402": {
"description": "Not a paid key, or the plan holds no more alerts (code plan_required)."
},
"429": {
"description": "Rate limit exceeded; honour Retry-After."
},
"503": {
"description": "Alerts are not yet enabled on this deployment (migration 048 pending)."
}
},
"x-codeSamples": [
{
"lang": "curl",
"label": "curl (Pro key)",
"source": "curl -s 'https://china-snapshot.com/api/alerts' \\\n -H \"Authorization: Bearer $CS_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n -d '{\"watch\":\"export-controls\",\"label\":\"Export controls\"}'"
},
{
"lang": "curl",
"label": "curl (Pro key)",
"source": "curl -s 'https://china-snapshot.com/api/alerts' \\\n -H \"Authorization: Bearer $CS_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n -d '{\"source\":\"MOFCOM\",\"channel\":\"webhook\",\"webhook_url\":\"https://hooks.example.com/cs\"}'"
}
]
}