> ## 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. # List units > The units the key can act on, paginated. Each one carries `tenant_id`, which the credit endpoints take, and `permissions`, the key's permissions in that unit. ## OpenAPI ````yaml /api-reference/openapi.json get /establishments 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: get: tags: - Establishments summary: List units description: >- The units the key can act on, paginated. Each one carries `tenant_id`, which the credit endpoints take, and `permissions`, the key's permissions in that unit. operationId: v1.establishments.index parameters: - name: page in: query description: Page number. schema: type: integer default: 1 - name: per_page in: query description: Units per page, up to 100. schema: type: integer default: 20 - 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 responses: '200': description: Paginated set of `Establishment` content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Establishment' links: type: object properties: first: type: - string - 'null' last: type: - string - 'null' prev: type: - string - 'null' next: type: - string - 'null' required: - first - last - prev - next meta: type: object properties: current_page: type: integer minimum: 1 from: type: - integer - 'null' minimum: 1 last_page: type: integer minimum: 1 links: type: array description: Generated paginator links. items: type: object properties: url: type: - string - 'null' label: type: string active: type: boolean required: - url - label - active path: type: - string - 'null' description: Base path for paginator generated URLs. per_page: type: integer description: Number of items shown per page. minimum: 0 to: type: - integer - 'null' description: Number of the last item in the slice. minimum: 1 total: type: integer description: Total number of items being paginated. minimum: 0 required: - current_page - from - last_page - links - path - per_page - to - total required: - data - links - meta 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: >- - `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: - 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 '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: Establishment: type: object properties: id: type: integer tenant_id: type: integer description: >- The chain the unit belongs to: the `{tenant}` of the credit endpoints. default_locale: $ref: '#/components/schemas/Locale' name: type: string slug: type: string description: type: - string - 'null' category: anyOf: - $ref: '#/components/schemas/EstablishmentCategory' - type: 'null' phone: type: - string - 'null' address_line: type: - string - 'null' city: type: - string - 'null' state: type: - string - 'null' postal_code: type: - string - 'null' country_code: type: - string - 'null' is_public: type: boolean latitude: type: - number - 'null' longitude: type: - number - 'null' logo_url: type: - string - 'null' description: The unit's logo, `null` when it has none. timezone: type: string status: $ref: '#/components/schemas/EstablishmentStatus' tenant_status: $ref: '#/components/schemas/TenantStatus' tenant_country_code: type: string description: >- The chain's billing country (ISO 3166-1 alpha-2); not the unit's own `country_code`. tenant_currency: type: string is_owner: type: boolean description: Always `false` for an API key. can_write_catalog: type: boolean description: Always `false` for an API key. permissions: type: array description: The key's permissions in this unit. items: $ref: '#/components/schemas/Permission' created_at: type: - string - 'null' updated_at: type: - string - 'null' required: - id - tenant_id - default_locale - name - slug - description - category - phone - address_line - city - state - postal_code - country_code - is_public - latitude - longitude - logo_url - timezone - status - tenant_status - tenant_country_code - tenant_currency - is_owner - can_write_catalog - permissions - created_at - updated_at title: Establishment 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 EstablishmentCategory: type: string description: |- | | |---| | `bakery`
Bakery. | | `restaurant`
Restaurant or food service. | | `retail`
Physical retail. | | `ecommerce`
Online store. | | `pharmacy`
Pharmacy. | | `clinic`
Medical clinic. | | `dental`
Dental clinic. | | `laboratory`
Laboratory. | | `blood_bank`
Blood bank. | | `education`
School or course. | | `beauty`
Beauty salon or barbershop. | | `fitness`
Gym or studio. | | `automotive`
Automotive services. | | `rental`
Equipment rental. | | `public_service`
Public service desk. | | `events`
Events and ticketing. | | `other`
Anything else. | enum: - bakery - restaurant - retail - ecommerce - pharmacy - clinic - dental - laboratory - blood_bank - education - beauty - fitness - automotive - rental - public_service - events - other title: EstablishmentCategory EstablishmentStatus: type: string description: |- | | |---| | `active`
Operating. | | `inactive`
Closed by the owner; takes no API calls. | | `suspended`
Suspended by the platform; takes no API calls. | enum: - active - inactive - suspended title: EstablishmentStatus TenantStatus: type: string description: >- | | |---| | `active`
Operating. | | `suspended`
Suspended by the platform; every API call of the chain is refused. | enum: - active - suspended title: TenantStatus Permission: type: string description: >- | | |---| | `create_items`
Create items. | | `edit_items`
Edit, archive and illustrate items. | | `view`
Read units, items, subscribers counts and dispatches. | | `dispatch_events`
Preview, send, schedule, reschedule and cancel alerts. | | `manage_billing`
Read the credit balance and statement. | enum: - create_items - edit_items - view - dispatch_events - manage_billing title: Permission 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.