Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Avelero/avelero/llms.txt

Use this file to discover all available pages before exploring further.

The Avelero API provides programmatic access to Digital Product Passport (DPP) management, brand configuration, product catalog operations, and integrations. The API uses a hybrid architecture combining tRPC for private endpoints and REST for public access.

​
Architecture overview

Avelero’s API is built with two distinct layers:
1

Private API (tRPC)

Type-safe procedures for authenticated brand management, catalog operations, and product administration. All private endpoints require authentication and brand context.
2

Public API (REST)

Open endpoints for accessing published Digital Product Passports, custom domain resolution, and barcode lookups. No authentication required.

​
Technology stack

The API server is built with:
  • Hono - Fast web framework for HTTP routing
  • tRPC - End-to-end type-safe RPC framework
  • Supabase - Authentication and storage backend
  • Drizzle ORM - Type-safe database queries
  • SuperJSON - Enhanced JSON serialization with Date, Map, Set support
  • WebSockets - Real-time progress updates for bulk operations

​
Base URLs

http://localhost:4100
The API runs on port 4100 in development, not the standard port 3000.

​
API design principles

​
Type safety

The tRPC layer provides end-to-end type safety from server to client. All inputs are validated with Zod schemas, and outputs are automatically typed.
apps/app/src/trpc/client.tsx
import type { AppRouter } from "@v1/api/src/trpc/routers/_app";
import { createTRPCClient, httpBatchLink } from "@trpc/client";
import superjson from "superjson";

const client = createTRPCClient<AppRouter>({
  links: [
    httpBatchLink({
      url: `${apiUrl}/trpc`,
      transformer: superjson,
    }),
  ],
});

​
Request batching

The tRPC client automatically batches multiple concurrent requests into a single HTTP call, reducing network overhead.
apps/app/src/trpc/client.tsx
httpBatchLink({
  url: `${apiUrl}/trpc`,
  transformer: superjson,
  maxURLLength: 2083, // Prevents GET requests from exceeding limits
})

​
Context-aware procedures

Every tRPC procedure receives a fully hydrated context containing:
  • Authenticated Supabase client - Bound to the request’s JWT token
  • Elevated admin client - For privileged operations (storage, user management)
  • User object - Authenticated user details or null
  • Brand context - Active brand ID and role (owner/member)
  • Database connection - Drizzle instance for transactional queries
  • Data loaders - Request-scoped batching and caching
  • Geo context - IP address and location hints
See apps/api/src/trpc/init.ts:37 for the complete context definition.

​
Middleware layers

The API enforces security through composable middleware: 
// No authentication required
export const publicProcedure = t.procedure;

​
API router structure

The API is organized into domain-specific routers, each handling a distinct area of functionality:
RouterDescriptionAuthentication
userUser profile, invites, brand management (list/create/leave)Protected
brandBrand lifecycle, members, invites, theme, collectionsProtected
catalogBrand catalog entities (attributes, materials, manufacturers)Protected
taxonomyGlobal read-only taxonomy dataProtected
productsProducts, variants, attributesProtected
bulkBulk import/export operationsProtected
compositePerformance-optimized composite endpointsProtected
summaryAggregated statisticsProtected
integrationsIntegration connections (Shopify), sync, mappingsProtected
notificationsUser-specific in-app notificationsProtected
internalServer-to-server endpoints (WebSocket progress updates)API key
dppPublicPublic DPP access by UPID or barcodePublic
See apps/api/src/trpc/routers/_app.ts:44 for the complete router definition.

​
Public REST endpoints

The following endpoints are accessible without authentication:

​
Health check

GET /health
Returns API status for health monitoring. Response: 
{
  "status": "ok"
}

​
Integration health

GET /integrations/health
Returns integration service status. Response: 
{
  "status": "ok",
  "service": "integrations"
}

​
OAuth routes

Integration OAuth flows use raw HTTP endpoints (not tRPC) because OAuth providers redirect directly to them:
  • GET /integrations/shopify/install - Initiate Shopify OAuth
  • GET /integrations/shopify/callback - Handle Shopify OAuth callback
See apps/api/src/index.ts:86 for OAuth route implementation.

​
WebSocket endpoints

The API provides real-time progress updates for long-running operations via WebSockets.

​
Import progress

ws://localhost:4100/ws/import-progress?jobId={jobId}
Subscribe to bulk import progress updates. The server emits progress events with status, percentage, and error details. See apps/api/src/lib/websocket-manager.ts for WebSocket implementation.

​
CORS configuration

The API enforces strict CORS policies with configurable origins:
apps/api/src/index.ts:24
cors({
  origin: (origin, c) => {
    const allowedOrigins = process.env.ALLOWED_API_ORIGINS?.split(",");
    // Supports exact matches and wildcard patterns
    return isAllowed ? origin : undefined;
  },
  allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"],
  allowHeaders: [
    "Authorization",
    "Content-Type",
    "accept-language",
    "x-trpc-source",
    "x-user-locale",
    "x-user-timezone",
    "x-user-country",
  ],
})
Configure allowed origins in the ALLOWED_API_ORIGINS environment variable (comma-separated list with optional wildcards).

​
Error handling

The API uses tRPC’s error system with standardized error codes:
  • UNAUTHORIZED - Missing or invalid authentication
  • FORBIDDEN - Insufficient permissions for the requested operation
  • BAD_REQUEST - Invalid input parameters or missing brand context
  • NOT_FOUND - Requested resource does not exist
  • INTERNAL_SERVER_ERROR - Unexpected server errors
All errors include a message field with human-readable descriptions. Never expose sensitive information in error messages.

​
Next steps

Authentication

Learn how to authenticate API requests with JWT tokens

Products API

Explore the products API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us