API Shield | Koze | Primitives Docs
Primitives

API Shield

Generate OpenAPI for Cloudflare API Shield Schema Validation

Koze treats Cloudflare API Shield as a route-adjacent API contract. Put an *.api-shield.ts file beside the API route it describes, and Koze generates the Cloudflare handoff files in a visible _cloudflare/ folder:

src/routes/api/v1/items/[id]/index.ts
src/routes/api/v1/items/[id]/index.api-shield.ts

_cloudflare/api-shield/openapi.json
_cloudflare/api-shield/api-shield.tf
_cloudflare/api-shield/README.md

Use those files with Cloudflare API Shield Schema Validation to protect your API routes with the same contract metadata you keep next to the route source.

Route file

export async function GET() {
  return Response.json(await loadItem());
}

API Shield file

// src/routes/api/v1/items/[id]/index.api-shield.ts
export default {
  GET: {
    operationId: 'getItem',
    summary: 'Read an item',
    auth: 'required',
    tags: ['items'],
    params: {
      id: { type: 'string', format: 'uuid' },
    },
    query: {
      include: { type: 'string' },
    },
    responses: {
      200: { description: 'Item found' },
      404: { description: 'Item not found' },
    },
  },
} as const;

The sidecar file name follows the route file name: items.ts uses items.api-shield.ts, and index.ts uses index.api-shield.ts. Koze adds the route pattern, exported methods, and file path automatically. Dynamic segments become OpenAPI parameters, so /api/v1/items/:id becomes /api/v1/items/{id}.

Route manifest exports still work for compatibility, but *.api-shield.ts is the recommended source because the file name says exactly what it feeds.

Vite options

API Shield generation is enabled by default when API routes exist.

koze({
  apiShield: {
    title: 'Inventory API',
    version: '2026.05',
    servers: ['https://api.example.com'],
    include: ['/api/v1'],
    // outputPath: '_cloudflare/api-shield/openapi.json',
  },
});

Set apiShield: false to disable the artifact.

Use include when only part of your API route tree should be exported to an API Shield schema. For example, include: ['/api/v1'] exports /api/v1 and /api/v1/items/{id}, but leaves internal app routes like /api/reports out of the generated OpenAPI file.

Cloudflare setup

Upload _cloudflare/api-shield/openapi.json in Security > API Shield > Schema validation, or apply the generated _cloudflare/api-shield/api-shield.tf helper after setting zone_id and api_host. Cloudflare's dashboard upload can add endpoints to Endpoint Management automatically; API/Terraform flows may require adding endpoints separately.

API Shield settings such as JWT validation rules, mTLS, rate limiting, and mitigation actions still live in Cloudflare. Koze's job is to make the schema and Endpoint Management source of truth native to the framework without hiding the handoff files inside compiled internals.

Related Cloudflare docs: