> ## 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.

# Create an item

> Creates an item people can subscribe to and the unit can alert. `translations` needs the block of the chain's default language with a `name`. `external_reference` is your own code for the item (SKU, procedure code): unique among the unit's non-archived items, matched exactly and case-sensitive; a duplicate is a 409. Send an `Idempotency-Key` so a retry after a timeout does not create the item twice.



## OpenAPI

````yaml /api-reference/openapi.json post /establishments/{establishment}/items
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 <key>`. 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:
    post:
      tags:
        - Items
      summary: Create an item
      description: >-
        Creates an item people can subscribe to and the unit can alert.
        `translations` needs the block of the chain's default language with a
        `name`. `external_reference` is your own code for the item (SKU,
        procedure code): unique among the unit's non-archived items, matched
        exactly and case-sensitive; a duplicate is a 409. Send an
        `Idempotency-Key` so a retry after a timeout does not create the item
        twice.
      operationId: v1.establishments.items.store
      parameters:
        - name: establishment
          in: path
          required: true
          description: The establishment 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/CreateItemRequest'
      responses:
        '201':
          description: '`Item`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Item'
                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.

            - `item_external_reference_taken`: Another item of this unit already
            uses this external reference.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - idempotency_request_in_progress
                          - item_external_reference_taken
          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: >-
            - `idempotency_key_reused`: This Idempotency-Key was already used
            for a different request.

            - `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:
                          - idempotency_key_reused
                          - 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. Wait the seconds in `Retry-After`.
          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:
    CreateItemRequest:
      type: object
      properties:
        queue_type:
          $ref: '#/components/schemas/QueueType'
        product_catalog_id:
          type:
            - integer
            - 'null'
        requires_sensitive_consent:
          type: boolean
        external_reference:
          type:
            - string
            - 'null'
          maxLength: 100
        attributes:
          type:
            - object
            - 'null'
          description: >-
            Free-form object of up to 50 keys whose values are scalars, `null`
            or lists of scalars.
          additionalProperties: {}
        translations:
          type: object
          description: >-
            Name and description per language, keyed by locale (`pt_BR`, `en`).
            The block of the chain's default language is required and must carry
            a `name` (up to 255 characters); `description` (up to 2000) is
            optional. Required unless `product_catalog_id` supplies the copy.
          properties:
            pt_BR:
              type: object
              properties:
                name:
                  type: string
                description:
                  type:
                    - string
                    - 'null'
              required:
                - name
            en:
              type: object
              properties:
                name:
                  type: string
                description:
                  type:
                    - string
                    - 'null'
              required:
                - name
      required:
        - queue_type
      title: CreateItemRequest
    Item:
      type: object
      properties:
        id:
          type: integer
        establishment_id:
          type: integer
        product_catalog_id:
          type:
            - integer
            - 'null'
          description: The chain-catalog product this item was created from, if any.
        public_code:
          type: string
          description: Short, immutable code printed on the QR sticker.
        external_reference:
          type:
            - string
            - 'null'
          description: >-
            Your own code for the item (SKU, procedure code). Unique per unit
            among non-archived items; matched exactly, case-sensitive.
        public_url:
          type: string
          description: The public page people subscribe from.
        qr_code_url:
          type: string
          description: The QR code image endpoint of this item.
        name:
          type:
            - string
            - 'null'
          description: >-
            In `content_locale`: the requested language, or the fallback when it
            has no translation.
        description:
          type:
            - string
            - 'null'
          description: In `content_locale`, like `name`.
        content_locale:
          $ref: '#/components/schemas/Locale'
          description: The language `name` and `description` above were served in.
        translations:
          type: object
          description: Every translation, keyed by locale (`pt_BR`, `en`).
          additionalProperties:
            type: object
            properties:
              name:
                type: string
              description:
                type:
                  - string
                  - 'null'
            required:
              - name
              - description
        image_url:
          type:
            - string
            - 'null'
          description: The item's picture, `null` when it has none.
        queue_type:
          $ref: '#/components/schemas/QueueType'
          description: >-
            How subscriptions behave after an alert: `single` ends them,
            `recurring` keeps them.

            | |

            |---|

            | `single` <br/> One-time alert: a subscription ends after its first
            alert. |

            | `recurring` <br/> Recurring alert: the subscription stays and is
            alerted every time. |
        status:
          $ref: '#/components/schemas/ItemStatus'
        attributes:
          type: object
          description: Free-form key/value data of the item.
          properties:
            id:
              type: integer
            establishment_id:
              type: integer
            product_catalog_id:
              type:
                - integer
                - 'null'
            public_code:
              type: string
            external_reference:
              type:
                - string
                - 'null'
            image_path:
              type:
                - string
                - 'null'
            queue_type:
              type: string
            status:
              type: string
            attributes:
              type:
                - string
                - 'null'
            subscribers_count:
              type: integer
            requires_sensitive_consent:
              type: string
            created_by_user_id:
              type:
                - integer
                - 'null'
            created_by_api_client_id:
              type:
                - integer
                - 'null'
            created_at:
              type:
                - string
                - 'null'
            updated_at:
              type:
                - string
                - 'null'
            deleted_at:
              type:
                - string
                - 'null'
        subscribers_count:
          type: integer
          description: People currently subscribed and eligible for the next alert.
        requires_sensitive_consent:
          type: boolean
          description: >-
            Whether subscribing asks for the sensitive-data consent (health
            items).
        created_by:
          type:
            - object
            - 'null'
          description: >-
            The person who created the item; `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 item; `null` when a person did.
          properties:
            id:
              type: integer
            name:
              type: string
          required:
            - id
            - name
        created_at:
          type:
            - string
            - 'null'
        updated_at:
          type:
            - string
            - 'null'
      required:
        - id
        - establishment_id
        - product_catalog_id
        - public_code
        - external_reference
        - public_url
        - qr_code_url
        - name
        - description
        - content_locale
        - translations
        - image_url
        - queue_type
        - status
        - attributes
        - subscribers_count
        - requires_sensitive_consent
        - created_by
        - created_by_api_client
        - created_at
        - updated_at
      title: Item
    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
    QueueType:
      type: string
      description: >-
        | |

        |---|

        | `single` <br/> One-time alert: a subscription ends after its first
        alert. |

        | `recurring` <br/> Recurring alert: the subscription stays and is
        alerted every time. |
      enum:
        - single
        - recurring
      title: QueueType
    Locale:
      type: string
      enum:
        - pt_BR
        - en
      title: Locale
    ItemStatus:
      type: string
      description: >-
        | |

        |---|

        | `active` <br/> Accepts subscriptions and alerts. |

        | `paused` <br/> Visible, but takes no new subscriptions or alerts until
        reactivated. |

        | `archived` <br/> Terminal: kept for history only. |
      enum:
        - active
        - paused
        - archived
      title: ItemStatus
  securitySchemes:
    apiKey:
      type: http
      description: >-
        An API key created by the chain owner in the panel (**Integrações** →
        **Nova chave**), sent as `Authorization: Bearer <key>`. The key
        (`<id>|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.