Routing API

The Gateway API routes requests to downstream services based on URL prefixes. Each route can be configured with authentication requirements and target service URLs.

Route Configuration

Routes are defined with a prefix, environment variable key, and route type:

const ROUTES = [
  { prefix: '/build', envKey: 'BUILD_SERVICE_URL', route: ProjectRoute.BUILD },
  { prefix: '/kv', envKey: 'KV_SERVICE_URL', route: ProjectRoute.KV },
  { prefix: '/core', envKey: 'CORE_SERVICE_URL', route: ProjectRoute.CORE },
];

Route Types

export enum ProjectRoute {
  AUTH = 'AUTH',
  KV = 'KV',
  BUILD = 'BUILD',
  CORE = 'CORE',
}

Routing Behavior

URL Rewriting

The gateway strips the route prefix and forwards the remaining path to the target service:

Request:  GET /build/projects/123
Prefix:   /build
Stripped: /projects/123
Forward:  {BUILD_SERVICE_URL}/projects/123

Query Parameters

Query parameters are preserved during URL rewriting:

Request:  GET /kv/data?filter=active&limit=10
Forward:  {KV_SERVICE_URL}/data?filter=active&limit=10

Headers

The gateway modifies headers before forwarding:

Removed: Authorization (prevents token leakage to downstream services)
Added: X-Gateway-Route (indicates which route matched)

headers.delete('Authorization');
headers.set('X-Gateway-Route', match.route);

Authentication Requirements

Required Authentication

/build routes always require authentication:

const shouldVerify = match.route === ProjectRoute.BUILD || 
                     request.headers.has('Authorization');

If no Authorization header is present for /build routes, the gateway returns 401 MISSING_TOKEN.

Optional Authentication

/kv and /core routes verify tokens only if provided:

If Authorization header is present → verify token
If no header → forward request without verification

Token Route Matching

Tokens must match the requested route (or be CORE/AUTH routes which have elevated privileges):

if (claims.route !== route && 
    claims.route !== ProjectRoute.CORE && 
    claims.route !== ProjectRoute.AUTH) {
  throw new Error('route_mismatch');
}

Routing Flow

Error Handling

All routing errors follow the unified GatewayErrorSchema:

{
  "route": "BUILD",
  "status": 502,
  "code": "MISSING_TARGET",
  "message": "Missing target for /build",
  "requestId": "uuid",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Common Routing Errors

Code	Status	Description
`NOT_FOUND`	404	No route matched the request path
`MISSING_TARGET`	502	Environment variable for target service URL not set
`MISSING_TOKEN`	401	Token required but not provided (for `/build` routes)
`INVALID_TOKEN`	403	Token verification failed
`ROUTE_MISMATCH`	403	Token route doesn’t match requested route

Configuration

Environment Variables

Configure target service URLs in wrangler.toml:

[vars]
BUILD_SERVICE_URL = "https://build.metacogna.ai"
KV_SERVICE_URL = "https://kv.metacogna.ai"
CORE_SERVICE_URL = "https://parti.metacogna.ai"

Service Bindings

For internal communication, use Cloudflare service bindings:

[[services]]
binding = "CORE_SERVICE"
service = "metacogna"

[[services]]
binding = "PORTAL_SERVICE"
service = "metacogna-ai-worker"

Service bindings are preferred over public URLs for security and performance.

Examples

Build Service Request

GET /build/projects HTTP/1.1
Host: api.metacogna.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Gateway forwards to: https://build.metacogna.ai/projects Headers added: X-Gateway-Route: BUILD Headers removed: Authorization

KV Service Request (Unauthenticated)

GET /kv/data HTTP/1.1
Host: api.metacogna.ai

Gateway forwards to: https://kv.metacogna.ai/data No authentication required (forwarded as-is)

Core Service Request (Authenticated)

POST /core/ingest HTTP/1.1
Host: api.metacogna.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{"data": "..."}

Gateway forwards to: https://parti.metacogna.ai/ingest Token verified before forwarding

Authentication API - Token generation and verification
Gateway Worker - Implementation details
Routing Matrix - Complete routing reference

Getting Started

Gateway API

MetaCogna RAG

MetaCogna.ai Landing

Parti Architecture

Design System

Route Configuration

Route Types

Routing Behavior

URL Rewriting

Query Parameters

Headers

Authentication Requirements

Required Authentication

Optional Authentication

Token Route Matching

Routing Flow

Error Handling

Common Routing Errors

Configuration

Environment Variables

Service Bindings

Examples

Build Service Request

KV Service Request (Unauthenticated)

Core Service Request (Authenticated)

​Route Configuration

​Route Types

​Routing Behavior

​URL Rewriting

​Query Parameters

​Headers

​Authentication Requirements

​Required Authentication

​Optional Authentication

​Token Route Matching

​Routing Flow

​Error Handling

​Common Routing Errors

​Configuration

​Environment Variables

​Service Bindings

​Examples

​Build Service Request

​KV Service Request (Unauthenticated)

​Core Service Request (Authenticated)

​Related Documentation

Route Configuration

Route Types

Routing Behavior

URL Rewriting

Query Parameters

Headers

Authentication Requirements

Required Authentication

Optional Authentication

Token Route Matching

Routing Flow

Error Handling

Common Routing Errors

Configuration

Environment Variables

Service Bindings

Examples

Build Service Request

KV Service Request (Unauthenticated)

Core Service Request (Authenticated)

Related Documentation