> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Publish up to 10 notifications > Not atomic. Entries are validated and queued independently, and the response reports each outcome against the caller's entry id. A 202 does NOT mean every entry was accepted — read `failed`. ## OpenAPI ````yaml /api-reference/specs/notifications.yaml post /v1/topics/{topic_id}/publish-batch openapi: 3.0.3 info: title: Basaltic Notifications API version: 1.0.0 description: | Publish/subscribe notification topics with email and webhook delivery. A topic is a fan-out root. Subscriptions bind it to endpoints; publishing to the topic delivers to every confirmed subscription whose filter policy matches the message. **Publishing is asynchronous.** Publish returns 202 as soon as the notification is durable and queued: no delivery has happened yet. Fan-out into per-subscription deliveries runs on a worker, so publish latency does not grow with subscriber count. Poll `GET /v1/messages/{message_id}` for the fan-out state and `GET /v1/deliveries?message_id=...` for per-endpoint outcomes. **Subscriptions must be confirmed.** Subscribe creates the subscription in `pending_confirmation` and sends a token to the endpoint — a link for email, a `subscription_confirmation` POST for webhooks. Nothing is delivered until the endpoint owner presents that token back. The confirmation window is 72 hours; unconfirmed subscriptions are reclaimed after it. If the handshake never arrived, `POST /v1/subscriptions/{id}/resend-confirmation` mints a fresh one — the original token is not recoverable, only its hash is stored. **Webhook endpoints must be publicly routable.** Endpoints resolving to loopback, RFC1918, link-local, or unique-local addresses are refused at subscribe time and again at delivery time. **Webhook deliveries are signed.** Each POST carries `X-Basaltic-Signature: v1,t=,s=`, an HMAC-SHA256 over `"."` keyed by the subscription's signing secret. The secret is returned once by Subscribe and is readable afterwards via the signing-secret endpoint. Verify by recomputing the MAC over the raw body you received — not a re-serialised copy — and reject timestamps more than five minutes from now. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://notifications.{region}.basaltic.sh description: Regional API endpoint variables: region: default: sa-saopaulo-1 description: Region code security: - SignatureAuth: [] tags: - name: Topics description: Fan-out topics - name: Subscriptions description: Endpoint subscriptions and their confirmation handshake - name: Messages description: Publishing and delivery status - name: Confirmations description: Unauthenticated endpoint-owner actions paths: /v1/topics/{topic_id}/publish-batch: parameters: - $ref: '#/components/parameters/TopicId' post: tags: - Messages summary: Publish up to 10 notifications description: | Not atomic. Entries are validated and queued independently, and the response reports each outcome against the caller's entry id. A 202 does NOT mean every entry was accepted — read `failed`. operationId: publishBatch parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublishBatchRequest' responses: '202': description: Batch processed; per-entry outcomes in the body. content: application/json: schema: $ref: '#/components/schemas/PublishBatchResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' components: parameters: TopicId: name: topic_id in: path required: true schema: type: string format: uuid example: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d IdempotencyKey: name: Idempotency-Key in: header description: >- Optional client-generated key that makes a create replay-safe. Retrying a request with the same key returns the original outcome verbatim instead of creating a duplicate resource. Reusing a key with a different request body is rejected (422); a request whose key is still being processed returns 409. Records are honored for 24 hours. Use a UUID or similarly unique token. required: false schema: type: string maxLength: 255 example: 550e8400-e29b-41d4-a716-446655440000 schemas: PublishBatchRequest: type: object required: - entries properties: entries: type: array minItems: 1 maxItems: 10 items: allOf: - type: object required: - id properties: id: type: string description: >- Caller-supplied correlation id, unique within the batch. Echoed back in the result. example: entry-1 - $ref: '#/components/schemas/PublishRequest' PublishBatchResponse: type: object properties: successful: type: array items: type: object required: - id - message_id properties: id: type: string example: entry-1 message_id: type: string format: uuid example: 019400aa-bbbb-7ccc-8ddd-eeeeffff0000 failed: type: array items: type: object required: - id - code - message properties: id: type: string example: entry-2 code: type: string example: NOTIFICATION_MESSAGE_TOO_LARGE message: type: string example: Notification exceeds the maximum size (262144 bytes) PublishRequest: type: object required: - message properties: subject: type: string maxLength: 100 description: Used as the email subject. No line breaks. example: Disk pressure on europa message: type: string maxLength: 262144 description: The payload. Up to 256 KiB. example: osd.22 reports a firmware impending failure message_structure: type: string enum: - '' - json description: | Omit to deliver `message` verbatim to every protocol. Set to `json` to have `message` read as an object of protocol keys (`default`, `email`, `https`, `http`), letting one publish carry a different payload per transport. A `default` key is required — it is what a protocol with no explicit entry gets. example: json attributes: $ref: '#/components/schemas/MessageAttributes' Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Error code identifying the type of error example: INVALID_INPUT message: type: string description: Human-readable error message example: Invalid request parameters request_id: type: string format: uuid description: Request ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 MessageAttributes: type: object description: | Typed attributes carried with a notification and matched against subscription filter policies. At most 20 attributes; values at most 1024 characters. Binary attributes are not accepted — they cannot be filtered on. additionalProperties: type: object required: - type - value properties: type: type: string enum: - String - Number example: String value: type: string example: critical example: severity: type: String value: critical latency: type: Number value: '250' responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Authentication required or token invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found request_id: 550e8400-e29b-41d4-a716-446655440000 Conflict: description: Resource conflict (e.g., already exists, invalid state) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: CONFLICT message: Resource with this name already exists request_id: 550e8400-e29b-41d4-a716-446655440000 UnprocessableEntity: description: | The request is well-formed but cannot be processed as sent. On the operations that accept `Idempotency-Key` this is the key-reuse case: the key was first seen with a different request payload, so replaying the stored outcome would answer a question the caller did not ask. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: IDEMPOTENCY_KEY_REUSED message: >- This Idempotency-Key was already used with a different request payload request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: SignatureAuth: type: apiKey in: header name: Authorization description: > Request signing with an access key issued to a service account. An HMAC-SHA256 over a canonical form of the request, close to AWS SigV4. The `basaltic` CLI signs for you. Send `Authorization`, `X-Date` (UTC, `YYYYMMDDTHHMMSSZ`) and `X-Nonce` (random per request); add `X-Content-Sha256` to bind a body, and `X-Amz-Security-Token` when using temporary credentials. ``` Authorization: BASALTIC-HMAC-SHA256 Credential=///basaltic/basaltic_request, SignedHeaders=host;x-date;x-nonce, Signature= ``` `` is the region code you are calling, or `global` for the global services. A signature is valid for 5 minutes from `X-Date`, and mutating requests are replay-guarded on the nonce. **Full signing procedure, including a working implementation:** https://docs.basaltic.sh/authentication ## Rate limits There is no global request budget. A limit applies only where an operation documents a `429`, and that operation says what it counts. Those responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and, on a `429`, `Retry-After` — read them rather than hard-coding a number. Retrying before `Retry-After` is refused and extends the window. Everything else is bounded by quota, not by request rate. ````