Endpoint#
GET /api/alerts
Saved alerts belong to the API key that created them. Starter holds 3, Pro 10, Scale 25 (x-api-tiers alerts). After every collection run each alert receives the new and revised documents that match it, by email to the key's own address or by a signed webhook.
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.
Responses and errors#
| HTTP status | Meaning |
|---|---|
| 200 | The alerts and the allowance. |
| 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": "GET",
"parameters": [],
"operationId": "listAlerts",
"summary": "List this key's saved alerts",
"description": "Saved alerts belong to the API key that created them. Starter holds 3, Pro 10, Scale 25 (x-api-tiers alerts). After every collection run each alert receives the new and revised documents that match it, by email to the key's own address or by a signed webhook.",
"tags": [
"keys",
"Retrieve changes",
"Manage access"
],
"responses": {
"200": {
"description": "The alerts and the allowance.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"alerts",
"limit",
"used"
],
"properties": {
"alerts": {
"type": "array",
"items": {
"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"
}
}
}
},
"limit": {
"type": "integer"
},
"used": {
"type": "integer"
}
}
}
}
}
},
"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",
"source": "curl -s -H \"Authorization: Bearer $CS_API_KEY\" 'https://china-snapshot.com/api/alerts'"
}
]
}