Introduction
The Cap API is a RESTful API that allows you to interact with videos, notifications, and user data programmatically. Built with Next.js and Effect.ts for type-safe, composable operations.Base URL
Production
Self-Hosted
API Structure
The Cap API is organized into several main routes:Authentication
Authenticate requests and manage sessions
Videos
Create, read, update, and delete videos
Notifications
Manage user notifications
API Contracts
The API uses@ts-rest for type-safe API contracts defined in packages/web-api-contract:
Request Format
All API requests should include:Headers
Authentication
Most endpoints require authentication via:- Session cookies (for web app)
- Bearer token (for desktop app and API integrations)
Response Format
All API responses follow a consistent structure:Success Response
Error Response
Status Codes
The API uses standard HTTP status codes:Request succeeded
Resource created successfully
Invalid request parameters
Authentication required or invalid
Insufficient permissions
Resource not found
Server error occurred
Rate Limiting
The API does not currently enforce rate limiting on self-hosted instances. The production instance at cap.so may implement rate limiting in the future.Versioning
The API is currently unversioned. Breaking changes will be communicated through:- GitHub releases
- Documentation updates
- Discord announcements
API Architecture
Effect.ts Integration
API routes are built using@effect/platform HttpApi:
Type Safety
All endpoints are type-safe using Zod schemas:WebSocket Support
The API does not currently support WebSockets. Real-time updates are handled through:- Polling for desktop app
- Server-Sent Events for web app (planned)
SDK and Libraries
TypeScript Client
The desktop app includes a typed client:CORS
The API supports CORS for web requests. Allowed origins can be configured via environment variables.Next Steps
Authentication
Learn about authentication methods
Videos
Manage videos via API
Notifications
Access user notifications