Endpoint#
POST /api/key_signup
Self-serve, no account. Issues one Free key per email address and emails it with a quickstart (subject 'Your China Snapshot API key (and a 30-second start)', from contact@china-snapshot.com). The key is NOT in the response: read it from the email. Only when mail delivery fails is a Free key returned once as key with status key_shown_once. Every answer carries docs_url, openapi_url, llms_url, upgrade_url and, on success or 409, a next_steps array. Errors use one envelope with a stable error.code. Leave the website honeypot out. Send no browser Origin header, or https://china-snapshot.com. Limited to 5 requests per 10 minutes per IP.
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": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 254,
"description": "Where the key is emailed. One live key per address."
}
}
},
"example": {
"email": "you@example.com"
}
},
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 254,
"description": "Where the key is emailed. One live key per address."
}
}
}
}
}
}Responses and errors#
| HTTP status | Meaning |
|---|---|
| 201 | Key issued. status=key_emailed: check the inbox. status=key_shown_once: delivery failed and the Free key is in key, once. |
| 400 | error.code invalid_email, email_required or invalid_request (body not JSON or form, or over 4 KB). |
| 403 | error.code forbidden_origin: a browser Origin other than https://china-snapshot.com. |
| 409 | error.code key_exists: this address already has a live key. next_steps explains how to find it in the inbox, replace it, or upgrade. |
| 429 | error.code rate_limited: too many requests from this network. Honour Retry-After; retry_after is in seconds. |
| 503 | error.code unavailable or email_failed: nothing was issued; retry later. |
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.
Request example (creates a key)#
Supply your own authorized address. This JSON illustrates the request body; the docs test runner never submits signup or checkout.
{"email": "YOUR_AUTHORIZED_EMAIL"}Use Content-Type: application/json and Accept: application/json. Follow next_steps; normally the key arrives by email.
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/key_signup",
"method": "POST",
"parameters": [],
"operationId": "requestApiKey",
"summary": "Request a Free API key by email",
"description": "Self-serve, no account. Issues one Free key per email address and emails it with a quickstart (subject 'Your China Snapshot API key (and a 30-second start)', from contact@china-snapshot.com). The key is NOT in the response: read it from the email. Only when mail delivery fails is a Free key returned once as `key` with status `key_shown_once`. Every answer carries docs_url, openapi_url, llms_url, upgrade_url and, on success or 409, a next_steps array. Errors use one envelope with a stable error.code. Leave the `website` honeypot out. Send no browser Origin header, or https://china-snapshot.com. Limited to 5 requests per 10 minutes per IP.",
"tags": [
"keys",
"Manage access"
],
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 254,
"description": "Where the key is emailed. One live key per address."
}
}
},
"example": {
"email": "you@example.com"
}
},
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 254,
"description": "Where the key is emailed. One live key per address."
}
}
}
}
}
},
"responses": {
"201": {
"description": "Key issued. status=key_emailed: check the inbox. status=key_shown_once: delivery failed and the Free key is in `key`, once.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ok",
"status",
"tier",
"emailed",
"limits",
"docs_url",
"openapi_url",
"upgrade_url",
"next_steps"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"status": {
"type": "string",
"enum": [
"key_emailed",
"key_shown_once"
]
},
"message": {
"type": "string"
},
"tier": {
"type": "string",
"enum": [
"free",
"pro"
],
"description": "pro when the address already has a paid subscription."
},
"prefix": {
"type": "string",
"description": "The key's first 18 characters, to recognise it later."
},
"emailed": {
"type": "boolean"
},
"limits": {
"type": "object",
"additionalProperties": true
},
"docs_url": {
"type": "string",
"format": "uri"
},
"openapi_url": {
"type": "string",
"format": "uri"
},
"llms_url": {
"type": "string",
"format": "uri"
},
"upgrade_url": {
"type": "string",
"format": "uri"
},
"support_email": {
"type": "string",
"format": "email"
},
"pro": {
"type": "object",
"additionalProperties": true,
"description": "What Pro adds, from x-api-tiers. Present for a Free key."
},
"next_steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Stable step id, e.g. check_inbox, first_request, read_docs, upgrade, replace_key, store_key."
},
"text": {
"type": "string"
},
"url": {
"type": "string"
},
"example": {
"type": "string",
"description": "A copy-paste command, with $CHINA_SNAPSHOT_KEY in place of the key."
},
"api": {
"type": "object",
"additionalProperties": true
}
}
}
},
"key": {
"type": "string",
"description": "Only with status key_shown_once. Shown once; never stored in plain text."
}
}
}
}
}
},
"400": {
"description": "error.code invalid_email, email_required or invalid_request (body not JSON or form, or over 4 KB).",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ok",
"status",
"error"
],
"properties": {
"ok": {
"type": "boolean",
"const": false
},
"status": {
"type": "string",
"const": "error"
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_request",
"invalid_email",
"email_required",
"forbidden_origin",
"method_not_allowed",
"key_exists",
"rate_limited",
"unavailable",
"email_failed"
]
},
"message": {
"type": "string"
},
"hint": {
"type": "string"
}
}
},
"retry_after": {
"type": "integer",
"description": "Seconds, on 429."
},
"docs_url": {
"type": "string",
"format": "uri"
},
"openapi_url": {
"type": "string",
"format": "uri"
},
"llms_url": {
"type": "string",
"format": "uri"
},
"upgrade_url": {
"type": "string",
"format": "uri"
},
"next_steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Stable step id, e.g. check_inbox, first_request, read_docs, upgrade, replace_key, store_key."
},
"text": {
"type": "string"
},
"url": {
"type": "string"
},
"example": {
"type": "string",
"description": "A copy-paste command, with $CHINA_SNAPSHOT_KEY in place of the key."
},
"api": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
},
"403": {
"description": "error.code forbidden_origin: a browser Origin other than https://china-snapshot.com.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ok",
"status",
"error"
],
"properties": {
"ok": {
"type": "boolean",
"const": false
},
"status": {
"type": "string",
"const": "error"
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_request",
"invalid_email",
"email_required",
"forbidden_origin",
"method_not_allowed",
"key_exists",
"rate_limited",
"unavailable",
"email_failed"
]
},
"message": {
"type": "string"
},
"hint": {
"type": "string"
}
}
},
"retry_after": {
"type": "integer",
"description": "Seconds, on 429."
},
"docs_url": {
"type": "string",
"format": "uri"
},
"openapi_url": {
"type": "string",
"format": "uri"
},
"llms_url": {
"type": "string",
"format": "uri"
},
"upgrade_url": {
"type": "string",
"format": "uri"
},
"next_steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Stable step id, e.g. check_inbox, first_request, read_docs, upgrade, replace_key, store_key."
},
"text": {
"type": "string"
},
"url": {
"type": "string"
},
"example": {
"type": "string",
"description": "A copy-paste command, with $CHINA_SNAPSHOT_KEY in place of the key."
},
"api": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
},
"409": {
"description": "error.code key_exists: this address already has a live key. next_steps explains how to find it in the inbox, replace it, or upgrade.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ok",
"status",
"error"
],
"properties": {
"ok": {
"type": "boolean",
"const": false
},
"status": {
"type": "string",
"const": "error"
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_request",
"invalid_email",
"email_required",
"forbidden_origin",
"method_not_allowed",
"key_exists",
"rate_limited",
"unavailable",
"email_failed"
]
},
"message": {
"type": "string"
},
"hint": {
"type": "string"
}
}
},
"retry_after": {
"type": "integer",
"description": "Seconds, on 429."
},
"docs_url": {
"type": "string",
"format": "uri"
},
"openapi_url": {
"type": "string",
"format": "uri"
},
"llms_url": {
"type": "string",
"format": "uri"
},
"upgrade_url": {
"type": "string",
"format": "uri"
},
"next_steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Stable step id, e.g. check_inbox, first_request, read_docs, upgrade, replace_key, store_key."
},
"text": {
"type": "string"
},
"url": {
"type": "string"
},
"example": {
"type": "string",
"description": "A copy-paste command, with $CHINA_SNAPSHOT_KEY in place of the key."
},
"api": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
},
"429": {
"description": "error.code rate_limited: too many requests from this network. Honour Retry-After; retry_after is in seconds.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ok",
"status",
"error"
],
"properties": {
"ok": {
"type": "boolean",
"const": false
},
"status": {
"type": "string",
"const": "error"
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_request",
"invalid_email",
"email_required",
"forbidden_origin",
"method_not_allowed",
"key_exists",
"rate_limited",
"unavailable",
"email_failed"
]
},
"message": {
"type": "string"
},
"hint": {
"type": "string"
}
}
},
"retry_after": {
"type": "integer",
"description": "Seconds, on 429."
},
"docs_url": {
"type": "string",
"format": "uri"
},
"openapi_url": {
"type": "string",
"format": "uri"
},
"llms_url": {
"type": "string",
"format": "uri"
},
"upgrade_url": {
"type": "string",
"format": "uri"
},
"next_steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Stable step id, e.g. check_inbox, first_request, read_docs, upgrade, replace_key, store_key."
},
"text": {
"type": "string"
},
"url": {
"type": "string"
},
"example": {
"type": "string",
"description": "A copy-paste command, with $CHINA_SNAPSHOT_KEY in place of the key."
},
"api": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
},
"503": {
"description": "error.code unavailable or email_failed: nothing was issued; retry later.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ok",
"status",
"error"
],
"properties": {
"ok": {
"type": "boolean",
"const": false
},
"status": {
"type": "string",
"const": "error"
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_request",
"invalid_email",
"email_required",
"forbidden_origin",
"method_not_allowed",
"key_exists",
"rate_limited",
"unavailable",
"email_failed"
]
},
"message": {
"type": "string"
},
"hint": {
"type": "string"
}
}
},
"retry_after": {
"type": "integer",
"description": "Seconds, on 429."
},
"docs_url": {
"type": "string",
"format": "uri"
},
"openapi_url": {
"type": "string",
"format": "uri"
},
"llms_url": {
"type": "string",
"format": "uri"
},
"upgrade_url": {
"type": "string",
"format": "uri"
},
"next_steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text"
],
"properties": {
"id": {
"type": "string",
"description": "Stable step id, e.g. check_inbox, first_request, read_docs, upgrade, replace_key, store_key."
},
"text": {
"type": "string"
},
"url": {
"type": "string"
},
"example": {
"type": "string",
"description": "A copy-paste command, with $CHINA_SNAPSHOT_KEY in place of the key."
},
"api": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "curl",
"label": "curl",
"source": "curl -s -X POST 'https://china-snapshot.com/api/key_signup' \\\n -H 'Content-Type: application/json' \\\n -d '{\"email\":\"you@example.com\"}'"
}
]
}