> ## Documentation Index > Fetch the complete documentation index at: https://docs.needalert.app/llms.txt > Use this file to discover all available pages before exploring further. # Send or schedule an alert > Without `scheduled_at`, notifies every eligible subscriber of the item now, debiting one credit per person after checking the balance; the response is the dispatch in `pending` (or already `dispatched` when nobody is waiting), and `GET` it to follow the send. With `scheduled_at` (ISO 8601, inside the window the preview's `schedule` reports), the alert is stored as `scheduled` and sent by the system at that time, after the same balance check. Send an `Idempotency-Key`: a retry after a timeout must not alert everyone twice. ## OpenAPI ````yaml /api-reference/openapi.json post /establishments/{establishment}/items/{item}/events openapi: 3.1.0 info: title: Need Alert API version: '1' description: >- The Need Alert API lets your own system — an ERP, an online store, a clinic's scheduling software — do what the panel does, without anyone at the screen: keep items in sync, read who is waiting, estimate the cost of an alert, send or schedule it, and follow your credit balance. Authenticate every request with an API key created by the chain owner in the panel (**Integrações**), sent as `Authorization: Bearer `. Always send `Accept: application/json`. Send `Idempotency-Key` on the two creating endpoints so a retry never creates an item or alerts the subscribers twice. Guides, in Portuguese and English: https://need-alert.mintlify.app/api/overview servers: - url: https://needalert.app/api/v1 description: Production security: - apiKey: [] tags: - name: Establishments - name: Items - name: Dispatches - name: Credits paths: /establishments/{establishment}/items/{item}/events: post: tags: - Dispatches summary: Send or schedule an alert description: >- Without `scheduled_at`, notifies every eligible subscriber of the item now, debiting one credit per person after checking the balance; the response is the dispatch in `pending` (or already `dispatched` when nobody is waiting), and `GET` it to follow the send. With `scheduled_at` (ISO 8601, inside the window the preview's `schedule` reports), the alert is stored as `scheduled` and sent by the system at that time, after the same balance check. Send an `Idempotency-Key`: a retry after a timeout must not alert everyone twice. operationId: v1.establishments.items.events.store parameters: - name: establishment in: path required: true description: The establishment ID schema: type: integer - name: item in: path required: true description: The item ID schema: type: integer - name: Idempotency-Key in: header description: >- Makes the request safe to retry. Send a value unique to this intended operation — a UUID v4 is recommended. The first response, a success **or** a business-rule refusal (any error with its own `code`, including `dispatch_in_progress` and `dispatch_too_soon`), is stored for 24 hours and replayed to a repetition with the same key and body, byte for byte and with its original `Content-Language`, under `Idempotent-Replayed: true`. A stored refusal is not retried: to try again for real, send a new key. `validation_failed`, `forbidden` and server errors are not stored. The same key with a different body is a 422 `idempotency_key_reused`; a repetition while the first request still runs is a 409 `idempotency_request_in_progress`. A replay counts towards the rate limit. schema: type: string pattern: ^[\x21-\x7E]{1,255}$ minLength: 1 maxLength: 255 example: 7f0c4e3a-5b7e-4a8e-9f1c-2d3e4f5a6b7c - name: Accept-Language in: header description: >- Language of `message` and of translated content such as item names (`pt-BR` or `en`). Without it, the chain's default language. schema: type: string enum: - pt-BR - en example: pt-BR - name: X-Request-Id in: header description: >- Your own correlation id (1–64 characters of `A-Za-z0-9._-`), echoed back; generated when absent. Quote it to support. schema: type: string pattern: ^[A-Za-z0-9._-]{1,64}$ minLength: 1 maxLength: 64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DispatchEventRequest' responses: '201': description: '`Event`' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Event' required: - data headers: Idempotent-Replayed: description: >- Present, as `true`, when this is the stored response of an earlier request with the same `Idempotency-Key`. schema: type: string enum: - 'true' Content-Language: description: The language of the body, BCP 47 (`pt-BR`, `en`). schema: type: string X-Request-Id: description: The request id, yours or the one generated here. schema: type: string '401': description: '- `unauthenticated`: Missing, malformed, expired or revoked API key.' content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - type: object properties: code: type: string enum: - unauthenticated headers: Content-Language: description: The language of the body, BCP 47 (`pt-BR`, `en`). schema: type: string X-Request-Id: description: The request id, yours or the one generated here. schema: type: string '403': description: >- - `establishment_unavailable`: The unit is inactive or suspended. - `forbidden`: The key lacks the permission this operation needs in this unit (`view`, `create_items`, `edit_items`, `dispatch_events` or `manage_billing`). - `tenant_suspended`: The chain that owns the key is suspended. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - type: object properties: code: type: string enum: - establishment_unavailable - forbidden - tenant_suspended headers: Content-Language: description: The language of the body, BCP 47 (`pt-BR`, `en`). schema: type: string X-Request-Id: description: The request id, yours or the one generated here. schema: type: string '404': description: >- - `not_found`: No such resource, or it is outside the key's scope. The API never reveals whether a resource you cannot see exists. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - type: object properties: code: type: string enum: - not_found headers: Content-Language: description: The language of the body, BCP 47 (`pt-BR`, `en`). schema: type: string X-Request-Id: description: The request id, yours or the one generated here. schema: type: string '409': description: >- - `idempotency_request_in_progress`: A request with this Idempotency-Key is still being processed. Try again in a moment. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - type: object properties: code: type: string enum: - idempotency_request_in_progress headers: Content-Language: description: The language of the body, BCP 47 (`pt-BR`, `en`). schema: type: string X-Request-Id: description: The request id, yours or the one generated here. schema: type: string '422': description: >- - `dispatch_in_progress`: A dispatch for this item is already in progress. - `dispatch_too_soon`: Wait a few seconds before dispatching this item again. - `idempotency_key_reused`: This Idempotency-Key was already used for a different request. - `insufficient_credits`: Insufficient credit balance for this dispatch. `errors`: `required` (integer), `available` (integer). - `item_not_dispatchable`: This item cannot be dispatched right now. - `schedule_slot_taken`: There is already a dispatch scheduled for this item at this minute. - `validation_failed`: Invalid input. `errors`: each invalid field mapped to its messages. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - type: object properties: code: type: string enum: - dispatch_in_progress - dispatch_too_soon - idempotency_key_reused - insufficient_credits - item_not_dispatchable - schedule_slot_taken - validation_failed headers: Content-Language: description: The language of the body, BCP 47 (`pt-BR`, `en`). schema: type: string X-Request-Id: description: The request id, yours or the one generated here. schema: type: string '429': description: >- - `too_many_requests`: Over the key's budget of 300 requests per minute, or over the 60 alert dispatches per minute of this route. Wait the seconds in `Retry-After`. The dispatch budget counts every attempt on this route, including ones later refused with 404, 403 or 422. The `X-RateLimit-*` headers of any response here, a successful one included, report the budget with fewer requests left, normally the dispatch one. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorEnvelope' - type: object properties: code: type: string enum: - too_many_requests headers: Retry-After: description: Seconds to wait before the next request. schema: type: integer X-RateLimit-Limit: description: Requests allowed per minute. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current minute. schema: type: integer Content-Language: description: The language of the body, BCP 47 (`pt-BR`, `en`). schema: type: string X-Request-Id: description: The request id, yours or the one generated here. schema: type: string components: schemas: DispatchEventRequest: type: object properties: message: type: string maxLength: 200 title: type: - string - 'null' maxLength: 120 scheduled_at: type: - string - 'null' format: date-time required: - message title: DispatchEventRequest Event: type: object properties: id: type: integer item: type: object properties: id: type: integer public_code: type: string name: type: - string - 'null' required: - id - public_code - name title: type: - string - 'null' message: type: string status: $ref: '#/components/schemas/EventStatus' scheduled_at: type: - string - 'null' description: When the alert is or was due; `null` for an immediate send. dispatched_at: type: - string - 'null' recipients_count: type: integer description: Subscribers the alert was sent to. credits_cost: type: integer description: 'Credits debited: one per recipient.' sent_count: type: integer failed_count: type: integer failure_reason: anyOf: - $ref: '#/components/schemas/EventFailureReason' - type: 'null' estimated_credits_cost: type: - integer - 'null' description: >- Scheduled alerts only: the cost estimated when the alert was scheduled or last rescheduled. warning_sent_at: type: - string - 'null' cancelled_at: type: - string - 'null' cancelled_by: type: - object - 'null' description: >- The person who cancelled; `null` when an API key did or the alert was not cancelled. properties: id: type: integer name: type: string required: - id - name cancelled_by_api_client: type: - object - 'null' description: >- The API key that cancelled; `null` when a person did or the alert was not cancelled. properties: id: type: integer name: type: string required: - id - name created_by: type: - object - 'null' description: >- The person who created the alert; `null` when an API key or the system did. properties: id: type: integer name: type: string required: - id - name created_by_api_client: type: - object - 'null' description: The API key that created the alert; `null` when a person did. properties: id: type: integer name: type: string required: - id - name created_at: type: - string - 'null' notifications: type: object description: 'Only on `GET …/events/{event}`: recipients per delivery status.' additionalProperties: type: integer required: - id - item - title - message - status - scheduled_at - dispatched_at - recipients_count - credits_cost - sent_count - failed_count - failure_reason - estimated_credits_cost - warning_sent_at - cancelled_at - cancelled_by - cancelled_by_api_client - created_by - created_by_api_client - created_at title: Event ErrorEnvelope: type: object description: The shape of every error response of the API. properties: message: type: string description: >- Translated (see `Content-Language`), for display only. Never program against it. code: type: string description: Stable `snake_case` identifier of the error. Program against it. errors: type: object description: >- Only on some errors: the invalid fields of a `validation_failed`, or extra data of a business-rule refusal. required: - message - code title: ErrorEnvelope EventStatus: type: string description: |- | | |---| | `pending`
Queued to be sent now. | | `processing`
Being sent. | | `dispatched`
Sent; see `sent_count` and `failed_count`. | | `failed`
Not sent; see `failure_reason`. | | `cancelled`
Cancelled while scheduled. | | `scheduled`
Waiting for `scheduled_at`. | enum: - pending - processing - dispatched - failed - cancelled - scheduled title: EventStatus EventFailureReason: type: string description: >- | | |---| | `processing_error`
An error while sending; the credits were not debited. | | `insufficient_credits`
The balance did not cover the send when it was due. | | `missed_schedule`
The scheduled time passed while the system was unavailable. | | `item_not_dispatchable`
The item, unit or chain could no longer be alerted when the send was due. | enum: - processing_error - insufficient_credits - missed_schedule - item_not_dispatchable title: EventFailureReason securitySchemes: apiKey: type: http description: >- An API key created by the chain owner in the panel (**Integrações** → **Nova chave**), sent as `Authorization: Bearer `. The key (`|na_…`) is shown once, at creation; rotate or revoke it on the same screen. It is a server secret: never ship it in browser or mobile code. scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.