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

# Upload the item's picture

> `multipart/form-data` with one `image` file: JPEG, PNG or WebP, up to 5 MB. Replaces the current picture; the response is the item with its new `image_url`.



## OpenAPI

````yaml /api-reference/openapi.json post /establishments/{establishment}/items/{item}/image
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/{item}/image:
    post:
      tags:
        - Items
      summary: Upload the item's picture
      description: >-
        `multipart/form-data` with one `image` file: JPEG, PNG or WebP, up to 5
        MB. Replaces the current picture; the response is the item with its new
        `image_url`.
      operationId: v1.establishments.items.image.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: 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:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadImageRequest'
      responses:
        '200':
          description: '`Item`'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Item'
                required:
                  - data
          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
        '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
        '413':
          description: '- `payload_too_large`: The file is over the size limit.'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - payload_too_large
          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: >-
            - `item_archived`: This item is archived and cannot be changed.

            - `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:
                          - item_archived
                          - 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:
    UploadImageRequest:
      type: object
      properties:
        image:
          type: string
          format: binary
          contentMediaType: application/octet-stream
          description: 'Maximum file size: 5120 kilobytes.'
      required:
        - image
      title: UploadImageRequest
    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
    Locale:
      type: string
      enum:
        - pt_BR
        - en
      title: Locale
    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
    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.