stable · api · 0.1.0
Register or reuse an FCM, APNs, or Web Push Delivery Endpoint
POST /api/v1/notification-endpoints
Capability Domain: Notifications
Authentication
projectCredential (notifications:write)
Scope: notifications:write
Parameters and request body
-
X-Correlation-ID— header, optionalX-Correlation-ID schema { "type": "string", "format": "uuid" }
Request schema
application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"channel",
"identifier"
],
"properties": {
"channel": {
"type": "string",
"enum": [
"fcm",
"apns",
"web_push"
]
},
"identifier": {
"type": "string",
"minLength": 20,
"maxLength": 4096
},
"locale": {
"type": "string",
"enum": [
"en",
"zh-TW",
"ja",
"zh-CN"
],
"default": "en",
"description": "Language of the endpoint verification notification; omitted values retain English."
}
}
}application/json request example
{
"channel": "fcm",
"identifier": "sandbox-fcm-device-token-0001"
}Responses and errors
| Status | Description |
|---|---|
200 | Safe Delivery Endpoint representation |
401 | Invalid or revoked Project Credential |
403 | Project Credential lacks the required scope |
422 | Request violates the public contract |
200 schema
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"channel",
"status",
"verified_at",
"consents"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"channel": {
"type": "string",
"enum": [
"fcm",
"apns",
"web_push"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"verified",
"verification_failed",
"verification_locked",
"revoked"
]
},
"verified_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"consents": {
"type": "array",
"items": {
"type": "object",
"required": [
"purpose",
"granted"
],
"properties": {
"purpose": {
"type": "string",
"maxLength": 120
},
"granted": {
"type": "boolean"
}
}
}
}
}
}
}
}401 schema
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"retryable",
"correlation_id",
"details"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"correlation_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object"
}
}
}
}
}403 schema
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"retryable",
"correlation_id",
"details"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"correlation_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object"
}
}
}
}
}422 schema
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"retryable",
"correlation_id",
"details"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"correlation_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object"
}
}
}
}
}200 example
{
"data": {
"id": "82000000-0000-4000-8000-000000000002",
"channel": "fcm",
"status": "pending",
"verified_at": null,
"consents": []
}
}Idempotency
The same Project Client, channel, and provider token resolve to the same Delivery Endpoint.