API docs by Redocly

Push Gateway API (1.2.1)

Download OpenAPI specification:

License: Apache 2.0

API for interacting with the Push Gateway

This API defines the endpoints and data formats for sending push notifications to a Push Gateway. It includes operations for submitting plain and encrypted notifications, as well as the expected responses and error handling.

The API is designed to be flexible and extensible, allowing for different notification formats and encryption methods as needed by various services implementing the Push Gateway specification.

Note: The base path for the endpoints MUST end with /push/v1, e.g. /push/v1/notify. This is to ensure compatibility with TI-M.

TI-M: Currently the URL MUST be an HTTPS URL with a path of _matrix/push/v1/notify

Push Gateway

Push plain data to the gateway

Submit a plain push notification to the Push Gateway. The notification will be sent to all devices listed in the devices array of the notification object.

This mimics the Matrix Push Gateway API in version 1.0.0.

Authorizations:
mtls
header Parameters
x-request-id
string [ 1 .. 128 ] characters
Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Client-generated identifier for this individual HTTP request, used purely for operational purposes (e.g. log correlation and support requests). It has no effect on the processing of the notification.

Support for this header is entirely OPTIONAL for every party involved. Clients (e.g. a Fachdienst) are not required to send this header, and a Push Gateway is not required to evaluate, log or return it, even if it is present on the request. Implementations MUST NOT fail or reject a request solely because this header is missing, unknown or unsupported.

If a client chooses to send this header, and the receiving Push Gateway chooses to support this feature, the Push Gateway SHOULD include the value in its log entries related to processing this request and SHOULD return the same value in the x-request-id response header, so that a single request can optionally be traced across the Fachdienst, Push Gateway and, where technically possible, the Push Provider. Clients MUST NOT rely on the value being logged or echoed back, as this is a best-effort, opt-in capability rather than a guaranteed contract.

Clients that make use of this header SHOULD generate a new, unique value (e.g. a UUIDv4) for every request. This identifier carries no semantic meaning, MUST NOT be used to correlate multiple requests (e.g. all requests of one batch or session) and MUST NOT contain personal or otherwise sensitive data.

Request Body schema: application/json
required
required
object (PlainNotification)

Information about the push notification

Responses

Request samples

Content type
application/json
{
  • "notification": {
    }
}

Response samples

Content type
application/json
{
  • "rejected": [
    ]
}

Push multiple plain notifications to the gateway in a single request

Submit multiple plain push notifications in a single batch request. This endpoint is optimized for high-throughput scenarios where multiple plain notifications need to be sent efficiently. The batch can contain up to a maximum of 100 notifications per request.

Authorizations:
mtls
header Parameters
x-request-id
string [ 1 .. 128 ] characters
Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Client-generated identifier for this individual HTTP request, used purely for operational purposes (e.g. log correlation and support requests). It has no effect on the processing of the notification.

Support for this header is entirely OPTIONAL for every party involved. Clients (e.g. a Fachdienst) are not required to send this header, and a Push Gateway is not required to evaluate, log or return it, even if it is present on the request. Implementations MUST NOT fail or reject a request solely because this header is missing, unknown or unsupported.

If a client chooses to send this header, and the receiving Push Gateway chooses to support this feature, the Push Gateway SHOULD include the value in its log entries related to processing this request and SHOULD return the same value in the x-request-id response header, so that a single request can optionally be traced across the Fachdienst, Push Gateway and, where technically possible, the Push Provider. Clients MUST NOT rely on the value being logged or echoed back, as this is a best-effort, opt-in capability rather than a guaranteed contract.

Clients that make use of this header SHOULD generate a new, unique value (e.g. a UUIDv4) for every request. This identifier carries no semantic meaning, MUST NOT be used to correlate multiple requests (e.g. all requests of one batch or session) and MUST NOT contain personal or otherwise sensitive data.

Request Body schema: application/json
required
required
Array of objects [ 1 .. 100 ] items unique

Array of plain notifications to process in this batch

Responses

Request samples

Content type
application/json
{
  • "notifications": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "results": [
    ],
  • "summary": {
    }
}

Push multiple encrypted notifications to the gateway in a single request

Submit multiple encrypted push notifications in a single batch request. This endpoint is optimized for high-throughput scenarios where multiple encrypted notifications need to be sent efficiently. The batch can contain up to a maximum of 100 notifications per request.

Authorizations:
mtls
header Parameters
x-request-id
string [ 1 .. 128 ] characters
Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Client-generated identifier for this individual HTTP request, used purely for operational purposes (e.g. log correlation and support requests). It has no effect on the processing of the notification.

Support for this header is entirely OPTIONAL for every party involved. Clients (e.g. a Fachdienst) are not required to send this header, and a Push Gateway is not required to evaluate, log or return it, even if it is present on the request. Implementations MUST NOT fail or reject a request solely because this header is missing, unknown or unsupported.

If a client chooses to send this header, and the receiving Push Gateway chooses to support this feature, the Push Gateway SHOULD include the value in its log entries related to processing this request and SHOULD return the same value in the x-request-id response header, so that a single request can optionally be traced across the Fachdienst, Push Gateway and, where technically possible, the Push Provider. Clients MUST NOT rely on the value being logged or echoed back, as this is a best-effort, opt-in capability rather than a guaranteed contract.

Clients that make use of this header SHOULD generate a new, unique value (e.g. a UUIDv4) for every request. This identifier carries no semantic meaning, MUST NOT be used to correlate multiple requests (e.g. all requests of one batch or session) and MUST NOT contain personal or otherwise sensitive data.

Request Body schema: application/json
required
required
Array of objects [ 1 .. 100 ] items unique

Array of encrypted notifications to process in this batch

Responses

Request samples

Content type
application/json
{
  • "notifications": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "results": [
    ],
  • "summary": {
    }
}