> ## Documentation Index > Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt > Use this file to discover all available pages before exploring further. # Criar Chave de API ## OpenAPI ````yaml POST /api/workspace/{workspaceId}/api-keys openapi: 3.1.0 info: title: Alana Shopping B2B API version: 1.0.0 description: >- Production API for Alana Shopping B2B - workspace management, brand catalog, product optimization, and AI-powered content generation termsOfService: https://alana.shopping/terms contact: name: Alana Support email: help@alana.shopping license: name: Proprietary servers: - url: https://app.alana.shopping description: Production API security: [] tags: - name: Workspace description: Workspace settings, security, and configuration management - name: Members description: Member management and role-based access control - name: Brands description: Brand management and AI specifications - name: Catalogs description: Catalog management, publishing, and merging - name: Products description: Product management and bulk import - name: AI Services description: AI-powered content generation and chat - name: Billing description: Billing, invoicing, and usage management - name: API Keys description: API key management and revocation - name: Integrations description: Third-party integrations and OAuth - name: MCP description: >- Model Context Protocol — programmatic product ingestion via M2M authentication - name: MCP Channel description: >- MCP SSE channel — AI agent protocol endpoint using JSON-RPC 2.0 over HTTP+SSE transport. Supports initialize handshake, tools/list enumeration, and tools/call execution for all available Discovery tools. - name: Workspaces description: Workspace listing and discovery for authenticated users - name: Authentication description: Passwordless authentication — OTP-based login and session management - name: Auth description: Authentication webhooks — Auth0 Log Streams and SCIM provisioning - name: SSO description: Enterprise SSO connection management (SAML and OIDC) - name: AI Media Jobs description: >- Async AI media processing jobs — video generation, virtual try-on, image editing, audio. Lifecycle: pending → processing → completed | failed | cancelled. - name: AI Media description: AI-powered media generation, editing, and analysis endpoints - name: Look Library description: Browse and manage saved look compositions - name: Feed description: >- Pull-based catalog feed — returns full versioned catalog snapshots in platform-native formats (VTEX, Shopify, Meta, Google AI/Shopping, ChatGPT plugin). Authenticated via Auth0 M2M with mcp:feed:read scope. - name: Composio Ingest description: >- Shopify and WooCommerce store connection via Composio OAuth. Supports connect, list, disconnect, and re-sync flows. Re-sync triggers the full bronze→silver→gold→Publish pipeline producing a new catalog_versions entry. - name: Webhooks description: >- Webhook channel — push-based catalog delta delivery on Publish. Sellers register HTTPS endpoints per catalog with an HMAC signing secret. On every Publish, Alana dispatches a signed POST with the catalog delta (added/removed/modified) formatted for the target platform (VTEX, Shopify, Meta, Google, WooCommerce, or custom). Secrets are stored AES-256-GCM encrypted. Signature in X-Alana-Signature header (sha256=). Endpoints: GET/POST /webhooks (list/create), DELETE /webhooks/{subscriptionId}, POST /webhooks/dispatch (full push). - name: Canvas description: Multi-product Canvas whiteboard — commit typed components to registry - name: Hub description: >- Catalog Hub — browse and preview Market Catalogs (open and paid) across all workspaces. Phase 42: browse and preview. Phase 43: clone and subscribe. All Hub endpoints are rate limited. Clone: 5/workspace/hour. Search: 60/user/minute. Preview: 30/user/minute. - name: KB Integration description: >- Endpoints for the shopping-b2b-kb ETL pipeline. Receives pipeline pushes and creates versioned catalog entries with full provenance. - name: Search API v1 description: >- Semantic product search API — Algolia-compatible response format for InstantSearch SDK integration. Authenticated via API key (X-API-Key header). Rate limited: 1,000 req/min per key, 100 req/min per key+IP. - name: Facet Config API v1 description: Manage facet display configuration for workspace search filters - name: Browse API v1 description: Category browse endpoint - name: Recommendations API v1 description: >- Product recommendation API — 8 models (5 catalog-based + 3 event-based). Authenticated via API key. Event-based models fall back to catalog models when event volume is insufficient. - name: Synonyms API v1 description: >- Manage search query synonyms for workspace. Supports regular (bidirectional) and one-way synonym types. Synonyms are applied automatically during query understanding before embedding generation. - name: Analytics API v1 description: >- Search analytics endpoints for merchants. Returns top searches, no-results queries, click-through rates, and facet usage statistics. All results cached 1h. Authenticated via API key. - name: Personalization Analytics API v1 description: >- Personalization effectiveness analytics: lift metrics (CTR/conversion delta vs baseline), cold start efficiency (events-to-personalization distribution), per-model recommendation performance, and Thompson Sampling bandit convergence state. All results cached 1h. Authenticated via API key. - name: Re-Ranking description: >- Two-tower re-ranking pipeline configuration. Controls personalization blend weight, diversity limits, and cold start behavior. - name: Contextual Bandits description: >- Thompson Sampling bandit engine that dynamically adjusts the personalization blend weight (alpha) per search based on observed engagement. Inspect convergence metrics and reset arm state via these endpoints. - name: Recommendations description: Product recommendation endpoints - name: Language description: Workspace language configuration for multi-language search - name: MCP Feed description: >- Canal 1 — AI Platform Feed API (Google Shopping, OpenAI Commerce, VTEX, Shopify, Nuvemshop) - name: Visibility description: >- AI Visibility monitoring — track product presence in Google SERP, ChatGPT, Resumo AI do Google and other AI platforms - name: Serving Configs description: Serving configuration management and presets - name: Surfaces description: Surface-specific product content resolution and customization - name: AI Prompt Templates description: >- Prompt template management with immutable versioning and {{variable}} interpolation - name: Canvas Workflows description: >- Canvas workflow definitions — multi-step automation with action validation, dependency ordering, and soft-delete lifecycle - name: Background Jobs description: >- Background job tracking for async work processed by Render workers via BullMQ (ADR 021). Lifecycle: queued → active → completed | failed. Supports in-app toast notifications on terminal state transitions and optional email notifications (notify_email opt-in). Poll GET /jobs/{jobId} for progress bars, ETA, and status updates. - name: Prompt Intelligence description: >- AI Prompt Intelligence — discover, track, and analyze what questions users ask AI platforms about your products. - name: Dashboards description: >- Configurable per-brand dashboards composed of registered widget types (counter, time_series, breakdown_bar, funnel, table, top_n) over agent events. Aggregations run with parameterized SQL against DO Postgres and are workspace+brand-scoped by construction. paths: /api/workspace/{workspaceId}/api-keys: post: tags: - API Keys summary: Create API key operationId: createAPIKey parameters: - $ref: '#/components/parameters/workspaceId' requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string minLength: 1 maxLength: 255 permissions: type: array items: type: string expires_at: type: - string - 'null' format: date-time brand_id: type: - string - 'null' format: uuid description: >- Phase 176-05: brand-scoped key. When set, this key can only access products and resources belonging to the specified brand. Omit or set to null for workspace-wide access. responses: '201': description: API key created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/APIKey' - type: object properties: secret: type: string description: Full API key (only shown on creation) '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '429': $ref: '#/components/responses/TooManyRequestsError' '500': $ref: '#/components/responses/InternalServerError' security: - bearer: [] components: parameters: workspaceId: name: workspaceId in: path required: true description: The workspace ID schema: type: string pattern: ^ws_[a-z0-9]+$ schemas: APIKey: type: object required: - id - workspace_id - name - key_prefix - created_at properties: id: type: string workspace_id: type: string name: type: string key_prefix: type: string description: First 10 characters of the API key permissions: type: array items: type: string last_used_at: type: - string - 'null' format: date-time expires_at: type: - string - 'null' format: date-time created_by: type: string created_at: type: string format: date-time brand_id: type: - string - 'null' format: uuid description: >- Phase 176-05: brand scope. Non-null means this key is restricted to resources of the specified brand. Error: type: object required: - error properties: error: $ref: '#/components/schemas/ApiErrorBody' ApiErrorBody: type: object description: Standardized error body (Phase 86-02) required: - code - message properties: code: type: string description: Machine-readable error code enum: - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - BAD_REQUEST - RATE_LIMITED - INTERNAL - CONFLICT message: type: string description: Human-readable error description request_id: type: string description: Correlation ID for support and tracing responses: BadRequestError: description: Bad request - validation failed content: application/json: schema: $ref: '#/components/schemas/Error' example: error: INVALID_REQUEST details: field: email message: Invalid email format UnauthorizedError: description: Unauthorized - authentication required content: application/json: schema: $ref: '#/components/schemas/Error' example: error: UNAUTHORIZED details: message: Missing or invalid authentication token ForbiddenError: description: Forbidden - insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: error: FORBIDDEN details: message: User does not have permission to access this resource TooManyRequestsError: description: Too many requests — rate limit exceeded headers: X-RateLimit-Limit: schema: type: integer description: Maximum requests allowed in the window X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window Retry-After: schema: type: integer description: Seconds until the rate limit resets content: application/json: schema: type: object properties: error: type: string example: Too many requests InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: INTERNAL_SERVER_ERROR details: message: An unexpected error occurred securitySchemes: bearer: type: http scheme: bearer bearerFormat: JWT description: >- Bearer token authentication via Auth0. Users authenticate through Auth0 Universal Login. Include the access token in the Authorization header: `Authorization: Bearer ` ````