Route Handler Authoring Guide

Conventions for writing route handlers in agents-api/src/domains/**/routes/ and their corresponding CRUD tests.

Spread Pattern (Required)

When forwarding a validated request body to a DAL function, always spread the body. Never use explicit field-picking.

Correct Pattern

const body = c.req.valid('json');

const result = await createEntity(db)({
  ...body,
  id: body.id || generateId(),
});

Spread the full body first, then override specific fields with transformations.

Incorrect Pattern (Anti-Pattern)

const body = c.req.valid('json');

const result = await createEntity(db)({
  name: body.name,
  description: body.description,
  config: body.config,
  id: body.id || generateId(),
});

Explicit field-picking silently drops any field not listed. When new columns are added to the schema, the handler will not forward them — causing data loss bugs that are invisible until discovered in production.

Field Transformation Overrides

Some fields require transformation before storage. Place these after the spread so they override the raw values:

const body = c.req.valid('json');

const result = await createTrigger(db)({
  ...body,
  id: generateId(),
  hashedAuthentication: body.authentication
    ? await hashAuthentication(body.authentication)
    : null,
  createdBy: c.get('userId'),
});

Common transformations to preserve as overrides:

• ID generation: id: body.id || generateId()
• Null coercion: expiresAt: body.expiresAt || undefined
• Type coercion: position: String(body.position)
• Default values: enabled: body.enabled ?? true
• Authentication hashing: hashedAuthentication: await hashAuthentication(...)
• Computed fields: createdBy: c.get('userId')

CI Enforcement

The scripts/check-route-handler-patterns.mjs script runs in CI as part of pnpm check. It detects handlers that call c.req.valid('json') and access the body variable via explicit field-picking without a corresponding spread.

Allowlisting Exceptions

If a handler legitimately needs explicit field-picking (rare), add the comment:

// allow-field-picking

within the object literal block that requires the exception. Use this sparingly — most handlers should use the spread pattern.

Running Locally

pnpm check:route-handler-patterns

CRUD Test Requirements

Every entity with a route handler must have round-trip field persistence tests covering ALL schema fields.

Required Test Coverage

1. Create with all fields → GET → verify all fields match
2. Update each field individually → GET → verify updated value
3. Round-trip with all optional fields simultaneously → verify all persist
4. Null/undefined handling for optional fields
5. Field clearing (set to null) for nullable fields
6. Default values are applied and returned correctly

Test File Location

Tests live in agents-api/src/__tests__/manage/routes/crud/ and use makeRequest() from agents-api/src/__tests__/utils/testRequest.ts.

Exemplary Test Files

Use these as patterns for comprehensive field coverage:

• contextConfigs.test.ts — demonstrates full round-trip testing for all schema fields
• credentialReferences.test.ts — demonstrates create/update/read cycle for every field

Test Data Factories

Use helpers from agents-api/src/__tests__/utils/testHelpers.ts:

• createTestAgentData() — agent entity test data
• createTestToolData() — tool entity test data
• Additional helpers for other entity types

Example Test Pattern

it('should persist imageUrl field on create', async () => {
  const toolData = createTestToolData({
    imageUrl: 'https://example.com/icon.png',
  });

  const createRes = await makeRequest('POST', '/tools', toolData);
  expect(createRes.status).toBe(200);

  const getRes = await makeRequest('GET', `/tools/${createRes.body.id}`);
  expect(getRes.status).toBe(200);
  expect(getRes.body.imageUrl).toBe('https://example.com/icon.png');
});

it('should update imageUrl field', async () => {
  const createRes = await makeRequest('POST', '/tools', createTestToolData());

  const updateRes = await makeRequest('PATCH', `/tools/${createRes.body.id}`, {
    imageUrl: 'https://example.com/new-icon.png',
  });
  expect(updateRes.status).toBe(200);

  const getRes = await makeRequest('GET', `/tools/${updateRes.body.id}`);
  expect(getRes.body.imageUrl).toBe('https://example.com/new-icon.png');
});

Route Definition Pattern

All routes must use createProtectedRoute() with explicit authorization. See the createProtectedRoute section in CLAUDE.md for details on permission helpers.

import { createProtectedRoute } from '@inkeep/agents-core/middleware';
import { requireProjectPermission } from '../../middleware/projectAccess';

app.openapi(
  createProtectedRoute({
    method: 'post',
    path: '/',
    permission: requireProjectPermission('edit'),
    request: { body: { content: { 'application/json': { schema: CreateEntitySchema } } } },
    responses: { 200: { content: { 'application/json': { schema: EntitySchema } } } },
  }),
  async (c) => {
    const body = c.req.valid('json');
    const result = await createEntity(db)({ ...body, id: generateId() });
    return c.json(result);
  },
);

HTTP Method Conventions

Use the correct HTTP method for each CRUD operation. See the "CRUD HTTP Method Conventions" section in AGENTS.md for the full table and RFC references.

• PATCH is the canonical method for partial/sparse update operations
• PUT is reserved for full-resource replacement — existing PUT routes remain but new update routes must use PATCH
• When adding a PATCH route alongside an existing PUT route, extract the handler and route config to shared variables, register PATCH with the canonical operationId, and register PUT with a -put suffixed operationId and 'x-speakeasy-ignore': true