Skip to main content

​
Overview

The Pipeline API provides programmatic control over the Bronze, Silver, and Gold processing stages for product data. Use these endpoints to trigger normalization and scoring in bulk, monitor job progress, and configure pipeline behavior.

​
Architecture

The pipeline follows a three-stage medallion architecture (see Data Pipeline for the full conceptual overview): 
Bronze (ingest) → Silver (normalize) → Gold (score) → Repository
Each stage is independently triggerable. Bronze is automatic on import; Silver and Gold require explicit triggering unless auto-trigger is configured.

​
ADR reference

Pipeline architecture is documented in ADR-015 (Bronze/Silver/Gold Medallion Architecture), available in the internal architecture decision record log.

​
Base URL

All Pipeline API endpoints are scoped to a workspace and catalog: 
https://app.alana.shopping/api/workspace/{workspaceId}/catalogs/{catalogId}/
For pipeline settings (workspace-level): 
https://app.alana.shopping/api/workspace/{workspaceId}/settings/pipeline

​
Authentication

All endpoints require a Bearer token: 
Authorization: Bearer sk_live_your_api_key_here
API keys are scoped to a workspace. The key must have catalogs:write permission to trigger pipeline stages, and settings:write to modify pipeline settings. See API Keys for details on creating and managing keys.

​
Rate limits

TierRequests per minute
Free20
Pro120
Business600
EnterpriseCustom
Pipeline batch operations (Silver and Gold) consume additional quota based on the number of products processed:
  • Each product processed via Silver = 1 request unit
  • Each product processed via Gold = 2 request units

​
Endpoints

Batch Silver

POST /batch/silver — normalize a selection or entire catalog

Batch Gold

POST /batch/gold — score a selection or entire catalog

Pipeline Settings

GET/PUT /settings/pipeline — configure mappings and weights

​
Score function

The Gold score is a weighted sum across 7 stages: 
score = Σ (stage_weight × stage_score) / 100
Where stage_score for each stage is 0–100 based on field completeness and quality. Default weights:
StageWeight
Identity20
Taxonomy15
Content25
Media20
Pricing10
Attributes5
SEO5
Weights are customizable via Pipeline Settings.

​
Error responses

All pipeline endpoints return standard error shapes: 
{
  "error": {
    "code": "CATALOG_NOT_FOUND",
    "message": "Catalog cat_xyz does not exist in this workspace",
    "details": null
  }
}
Common error codes:
CodeHTTP statusDescription
CATALOG_NOT_FOUND404Catalog ID not found in workspace
INSUFFICIENT_PERMISSIONS403API key lacks required permission
RATE_LIMIT_EXCEEDED429Too many requests — back off and retry
JOB_ALREADY_RUNNING409A batch job is already in progress for this catalog
VALIDATION_ERROR422Request body failed validation
Last modified on March 18, 2026