stable · api · 0.1.0

Verify a channel Delivery Endpoint

POST /api/v1/notification-endpoints/{endpointId}/verify

Capability Domain: Notifications

Authentication

projectCredential (notifications:write)

Scope: notifications:write

Parameters and request body

X-Correlation-ID — header, optional
X-Correlation-ID schema
```
{
    "type": "string",
    "format": "uuid"
}
```

endpointId — path, required

endpointId schema

{
    "type": "string",
    "format": "uuid"
}

Request schema

application/json

application/json request schema

{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "token"
    ],
    "properties": {
        "token": {
            "type": "string",
            "minLength": 64,
            "maxLength": 64
        }
    }
}

application/json request example

{
    "token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Responses and errors

Status	Description
`200`	Verified Delivery Endpoint
`401`	Invalid or revoked Project Credential
`403`	Project Credential lacks the required scope
`422`	Request violates the public contract

200 schema

200 response 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

401 response 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

403 response 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

422 response 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

200 response example

{
    "data": {
        "id": "82000000-0000-4000-8000-000000000002",
        "channel": "fcm",
        "status": "verified",
        "verified_at": "2026-08-02T08:00:00Z",
        "consents": []
    }
}

Idempotency

Verification consumes the current token; inspect the endpoint before retrying an ambiguous response.