Skip to main content

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

https://cap.so/api

Self-Hosted

https://your-domain.com/api
You can configure your desktop app to connect to a self-hosted instance via: Settings → Cap Server URL

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:
export const contract = c.router({
  desktop,
  video: c.router({
    getTranscribeStatus: { /* ... */ },
    delete: { /* ... */ },
    getAnalytics: { /* ... */ },
  }),
  notifications: c.router({
    get: { /* ... */ },
  }),
});

Request Format

All API requests should include:

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>"
}

Authentication

Most endpoints require authentication via:
  • Session cookies (for web app)
  • Bearer token (for desktop app and API integrations)
See Authentication for details.

Response Format

All API responses follow a consistent structure:

Success Response

{
  "data": {
    // Response data
  }
}

Error Response

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Status Codes

The API uses standard HTTP status codes:
200
OK
Request succeeded
201
Created
Resource created successfully
400
Bad Request
Invalid request parameters
401
Unauthorized
Authentication required or invalid
403
Forbidden
Insufficient permissions
404
Not Found
Resource not found
500
Internal Server Error
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:
import { HttpApi, HttpApiBuilder } from "@effect/platform";
import { Effect } from "effect";

const api = HttpApiBuilder.group(ApiClass, "videos", (endpoints) =>
  endpoints.endpoint("list", {
    handler: () =>
      Effect.gen(function* () {
        const videos = yield* Videos;
        return yield* videos.list();
      }),
  })
);

export const { handler } = apiToHandler(ApiLive);

Type Safety

All endpoints are type-safe using Zod schemas:
import { z } from "zod";

const VideoSchema = z.object({
  id: z.string(),
  name: z.string(),
  ownerId: z.string(),
  createdAt: z.coerce.date(),
});

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:
import { contract } from "@cap/web-api-contract";
import { initClient } from "@ts-rest/core";

const client = initClient(contract, {
  baseUrl: "https://cap.so/api",
  baseHeaders: {
    Authorization: `Bearer ${token}`,
  },
});

const { status, body } = await client.video.getAnalytics({
  query: { videoId: "123" },
});

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

Build docs developers (and LLMs) love