> ## Documentation Index > Fetch the complete documentation index at: https://docs.mareaalcalina.com/llms.txt > Use this file to discover all available pages before exploring further. # Use this when an agent wants to create a Marea account on behalf of a user with one round-trip (account + storefront + verification email). > Creates a Firebase Auth user + Firestore user doc + restricted user key + (optionally) a starter storefront via createMenuCore + sends a 6-digit verification email. Returns 201, or 207 when the account was created but the storefront was not fully applied (plan-cap overflow, or the storefront could not be created at all — see errors[]). The account and userKey are returned either way; the userKey is returned ONCE — store it. ## OpenAPI ````yaml /openapi.json post /v1/users openapi: 3.1.0 info: title: Marea Alcalina API version: 1.0.0 servers: - url: https://api.mareaalcalina.com security: [] paths: /v1/users: post: summary: >- Use this when an agent wants to create a Marea account on behalf of a user with one round-trip (account + storefront + verification email). description: >- Creates a Firebase Auth user + Firestore user doc + restricted user key + (optionally) a starter storefront via createMenuCore + sends a 6-digit verification email. Returns 201, or 207 when the account was created but the storefront was not fully applied (plan-cap overflow, or the storefront could not be created at all — see errors[]). The account and userKey are returned either way; the userKey is returned ONCE — store it. operationId: createUser requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BootstrapInput' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/BootstrapResponse' '207': description: Partial success — see `errors[]` in the body content: application/json: schema: $ref: '#/components/schemas/BootstrapResponse' '400': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '401': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '403': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '404': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '409': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '410': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '413': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '429': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '500': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '503': description: §9.6 error envelope content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' security: - BearerAuth: [] components: schemas: BootstrapInput: type: object properties: email: type: string format: email displayName: type: string minLength: 1 maxLength: 200 country: type: - string - 'null' pattern: ^[A-Z]{2}$ language: type: - string - 'null' enum: - es - en - pt currency: type: - string - 'null' enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHF - CLP - CNY - COP - CRC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLE - SOS - SRD - SSP - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL businessType: type: - string - 'null' enum: - Restaurante - Comida a domicilio - Cafetería - Bar - Panadería y Repostería - Alimentos en la despensa - Bebidas Alcohólicas - Bebidas no alcohólicas - Licorería - Carnicería - Minimercado - Tienda de barrio - Moda - Belleza y cuidado personal - Barbería y salón de belleza - Estética y salud - Farmacia - Gimnasio - Joyería - Juguetes - Infantil - Mascotas - Muebles y decoración del hogar - Artículos para el hogar - Mejora del hogar - Electrodomésticos - Electrónicos - Celulares - Consolas y videojuegos - Instrumentos musicales - Herramientas - Artículos de oficina - Deportes - Cultura - Refacciones y autopartes - Taller automotriz - Vehículos - Organización de eventos - Servicios educativos - Servicios profesionales - Agencia de Marketing - Otro sourceAgent: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z0-9 _.-]+$ initialStorefront: allOf: - $ref: '#/components/schemas/StorefrontManifest' - type: - object - 'null' required: - email - displayName - sourceAgent BootstrapResponse: type: object properties: userId: type: string storefrontId: type: - string - 'null' pattern: ^stf_ userKey: type: string pattern: ^mk_user_ verificationStatus: type: string enum: - pending verificationExpiresAt: type: string format: date-time verificationDeliveryHint: type: string enum: - email-only appliedDefaults: $ref: '#/components/schemas/AppliedDefaults' idempotent: type: boolean errors: type: array items: type: object properties: type: type: string code: type: string message: type: string required: - type - code - message required: - userId - userKey - verificationStatus - verificationExpiresAt - verificationDeliveryHint - appliedDefaults ApiErrorResponse: type: object properties: error: $ref: '#/components/schemas/ApiErrorBody' required: - error description: §9.6 uniform error envelope. Every non-2xx response uses this shape. StorefrontManifest: type: object properties: name: type: string minLength: 1 maxLength: 100 language: type: string enum: - es - en - pt currency: type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHF - CLP - CNY - COP - CRC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLE - SOS - SRD - SSP - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL businessType: type: string enum: - Restaurante - Comida a domicilio - Cafetería - Bar - Panadería y Repostería - Alimentos en la despensa - Bebidas Alcohólicas - Bebidas no alcohólicas - Licorería - Carnicería - Minimercado - Tienda de barrio - Moda - Belleza y cuidado personal - Barbería y salón de belleza - Estética y salud - Farmacia - Gimnasio - Joyería - Juguetes - Infantil - Mascotas - Muebles y decoración del hogar - Artículos para el hogar - Mejora del hogar - Electrodomésticos - Electrónicos - Celulares - Consolas y videojuegos - Instrumentos musicales - Herramientas - Artículos de oficina - Deportes - Cultura - Refacciones y autopartes - Taller automotriz - Vehículos - Organización de eventos - Servicios educativos - Servicios profesionales - Agencia de Marketing - Otro branding: $ref: '#/components/schemas/StorefrontBranding' schedule: $ref: '#/components/schemas/StorefrontSchedule' delivery: $ref: '#/components/schemas/StorefrontDelivery' pickup: type: - boolean - 'null' dineIn: type: - boolean - 'null' whatsapp: type: - string - 'null' pattern: ^\+[1-9]\d{7,14}$ biography: anyOf: - type: object properties: title: type: string description: type: string required: - title - description - type: string enum: - auto - type: 'null' blocks: anyOf: - type: string enum: - auto - type: array items: {} - type: 'null' description: >- REPLACES the whole block list. On PATCH, send the complete array — anything you omit is removed, not merged. categories: type: - array - 'null' items: type: object properties: name: type: string position: type: - integer - 'null' required: - name description: >- REPLACES the whole category list. On PATCH, send the complete array — categories you omit are deleted, and products still referencing them keep an orphan category string. products: type: - array - 'null' items: $ref: '#/components/schemas/ProductManifest' maxItems: 100 hidden: type: - boolean - 'null' required: - name - language - currency - businessType description: >- Agent-facing storefront input shape (RFC §6.18.1). Every field is PATCHable per §6.18.1.1. AppliedDefaults: type: object properties: language: type: string enum: - es - en - pt currency: type: string country: type: string businessType: type: string required: - language - currency - country - businessType ApiErrorBody: type: object properties: type: type: string enum: - rate_limited - invalid_request - auth - not_found - plan_limit - internal - conflict - idempotency_conflict - service_unavailable - tos_not_accepted description: High-level error category. Agents branch on this. example: auth code: type: string description: Stable machine-readable code. example: missing_authorization message: type: string description: Human-readable, localized via Accept-Language. doc: type: string description: Link to the error reference in the docs. example: https://docs.mareaalcalina.com/concepts/errors param: type: - string - 'null' requestId: type: string example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84 recoverable: type: boolean retryAfterMs: type: - integer - 'null' nextActions: type: array items: $ref: '#/components/schemas/ApiNextAction' upgrade: $ref: '#/components/schemas/ApiErrorUpgrade' requiredScopes: type: array items: type: string heldScopes: type: array items: type: string required: - type - code - message - doc - param - requestId - recoverable - retryAfterMs - nextActions - upgrade StorefrontBranding: type: - object - 'null' properties: logoUrl: anyOf: - type: string format: uri - type: object properties: fileId: type: string required: - fileId - type: 'null' backgroundUrl: anyOf: - type: string format: uri - type: object properties: fileId: type: string required: - fileId - type: string enum: - auto - type: 'null' theme: anyOf: - type: object properties: primary: type: string secondary: type: string tertiary: type: string required: - primary - secondary - tertiary - type: object properties: preset: type: string required: - preset - type: 'null' font: type: - string - 'null' StorefrontSchedule: type: - object - 'null' properties: monday: type: - object - 'null' properties: open: type: string pattern: ^\d{2}:\d{2}$ close: type: string pattern: ^\d{2}:\d{2}$ closed: type: - boolean - 'null' tuesday: type: - object - 'null' properties: open: type: string pattern: ^\d{2}:\d{2}$ close: type: string pattern: ^\d{2}:\d{2}$ closed: type: - boolean - 'null' wednesday: type: - object - 'null' properties: open: type: string pattern: ^\d{2}:\d{2}$ close: type: string pattern: ^\d{2}:\d{2}$ closed: type: - boolean - 'null' thursday: type: - object - 'null' properties: open: type: string pattern: ^\d{2}:\d{2}$ close: type: string pattern: ^\d{2}:\d{2}$ closed: type: - boolean - 'null' friday: type: - object - 'null' properties: open: type: string pattern: ^\d{2}:\d{2}$ close: type: string pattern: ^\d{2}:\d{2}$ closed: type: - boolean - 'null' saturday: type: - object - 'null' properties: open: type: string pattern: ^\d{2}:\d{2}$ close: type: string pattern: ^\d{2}:\d{2}$ closed: type: - boolean - 'null' sunday: type: - object - 'null' properties: open: type: string pattern: ^\d{2}:\d{2}$ close: type: string pattern: ^\d{2}:\d{2}$ closed: type: - boolean - 'null' StorefrontDelivery: type: - object - 'null' properties: enabled: type: boolean type: type: - string - 'null' enum: - fixed - distance fixedPrice: type: - number - 'null' minimum: 0 ranges: type: - array - 'null' items: type: object properties: fromKm: type: number minimum: 0 toKm: type: number minimum: 0 price: type: number minimum: 0 required: - fromKm - toKm - price required: - enabled ProductManifest: type: object properties: title: type: string minLength: 1 maxLength: 200 description: type: - string - 'null' price: type: number minimum: 0 salePrice: type: - number - 'null' minimum: 0 category: type: - string - 'null' subcategory: type: - string - 'null' imageUrl: type: - string - 'null' format: uri thumbnailUrl: type: - string - 'null' format: uri sku: type: - string - 'null' slug: type: - string - 'null' position: type: - integer - 'null' cartProduct: type: - boolean - 'null' hide: type: - boolean - 'null' stock: type: - integer - 'null' minimum: 0 tags: type: - array - 'null' items: type: string extraProductsCategory: type: - array - 'null' items: $ref: '#/components/schemas/ExtraProductsCategory' required: - title - price description: >- Agent-facing product input shape. Mutability rule §6.18.1.1: every field PATCHable post-create. ApiNextAction: type: object properties: label: type: string example: Validate the JSON before retrying. method: type: - string - 'null' example: null url: type: - string - 'null' example: null required: - label - method - url description: A concrete action the agent can offer the user. ApiErrorUpgrade: type: - object - 'null' properties: currentPlan: type: string example: free requiredPlan: type: string example: pro upgradeUrl: type: string example: >- https://mareaalcalina.com/menus/profile?changePlan=basic&frequency=monthly&planSource=api previewUrl: type: string description: Optional preview link the agent can surface. required: - currentPlan - requiredPlan - upgradeUrl ExtraProductsCategory: type: object properties: title: type: string obligatory: type: boolean multipleOption: type: boolean maxOptions: type: integer minOptions: type: integer extraProducts: type: - array - 'null' items: $ref: '#/components/schemas/ExtraProductOption' required: - title - obligatory - multipleOption - maxOptions - minOptions ExtraProductOption: type: object properties: title: type: string price: type: number minimum: 0 available: type: boolean stock: type: - integer - 'null' required: - title - price - available securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: mk_dev_* | mk_user_* ````