# Corvidlabs Corvid Agent REST API

> REST API — Endpoint Development

- Skill: `tomevault-io/corvidlabs-corvid-agent-rest-api` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/corvidlabs-corvid-agent-rest-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/corvidlabs-corvid-agent-rest-api/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/corvidlabs-corvid-agent-rest-api

---


# REST API — Endpoint Development

Patterns for adding and modifying HTTP API endpoints in the corvid-agent server.

## Architecture

- **Runtime:** Bun's built-in HTTP server
- **Routes:** `server/routes/` — 34+ route modules
- **Registration:** `server/routes/index.ts` — all routes registered here
- **Middleware:** `server/middleware/` — auth, CORS, security checks

## Adding a New Endpoint

1. Create or edit a route handler file in `server/routes/`
2. Export a handler function that takes `(req: Request, ...params)` and returns `Response`
3. Register in `server/routes/index.ts`

### Route Handler Pattern

```typescript
import { createLogger } from '../lib/logger';

const log = createLogger('MyRoute');

export function handleMyEndpoint(req: Request): Response {
  // Parse request
  const url = new URL(req.url);
  const params = url.searchParams;

  // Business logic
  const result = doSomething();

  // Return JSON response
  return Response.json({ ok: true, data: result });
}
```

### Error Responses

```typescript
// 400 Bad Request
return Response.json({ error: 'Missing required field' }, { status: 400 });

// 404 Not Found
return Response.json({ error: 'Resource not found' }, { status: 404 });

// 500 Internal Server Error
return Response.json({ error: 'Internal server error' }, { status: 500 });
```

## Conventions

- Use `Response.json()` for all JSON responses
- Use typed error enums with `Sendable` conformance patterns
- Use `createLogger('RouteName')` for logging
- Named exports only (no default exports)
- TypeScript strict mode
- Input validation at the boundary (validate user/external input, trust internal code)

## Database Access

Use `bun:sqlite` for database queries. See the `database` skill for migration patterns.

```typescript
import { db } from '../db/schema';

const rows = db.query('SELECT * FROM agents WHERE id = ?').all(agentId);
```

## Authentication

Middleware in `server/middleware/` handles:
- API key validation
- Session token auth
- CORS headers
- Startup security checks (X-Forwarded-For validation)

---
> Source: [CorvidLabs/corvid-agent](https://github.com/CorvidLabs/corvid-agent) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-15 -->