# RIC Gateway

> RIC Gateway (Registry Interface Cube Gateway) is a trusted middleware service that provides secure, scoped access to OCME creator data. It acts as the bridge between CreatorCubiCubes and the central Registry, ensuring creators can only access data they're authorized to see.

RIC Gateway is part of the Open Commercial Media Ecosystem (OCME). It enables CreatorCubiCubes (custom creator experiences deployed on Cloudflare Workers for Platforms) to access creator content, revenue, analytics, and media files through a secure, JWT-authenticated API.

**Key Security Features:**
- All requests require JWT authentication via Sentinel
- All data is automatically scoped to the authenticated creator's email
- Creators can access content they own OR content where they're on the split sheet
- Storage keys are scoped to creator email hash for upload security
- No direct database access from user code—all queries go through trusted gateway

## Docs

- [API Overview](https://gateway-dev.theric.link/llms-full.txt): Complete API documentation with all endpoints, request/response formats, and integration patterns

## Endpoints

- [GET /api/profile](https://gateway-dev.theric.link/api/profile): Returns creator profile info and content statistics (requires JWT)
- [GET /api/content](https://gateway-dev.theric.link/api/content): Lists all content the creator owns or collaborates on (supports pagination, filtering, search)
- [GET /api/content/{did}](https://gateway-dev.theric.link/api/content/{did}): Returns detailed content info with associated media files
- [GET /api/content/{did}/download](https://gateway-dev.theric.link/api/content/{did}/download): Returns presigned URL for downloading media (expires in 1 hour)
- [GET /api/plays](https://gateway-dev.theric.link/api/plays): Returns play records and listening analytics for creator's content
- [GET /api/revenue](https://gateway-dev.theric.link/api/revenue): Returns payment records and revenue summary
- [POST /api/upload/init](https://gateway-dev.theric.link/api/upload/init): Initializes multipart upload (returns uploadId and storageKey)
- [POST /api/upload/chunk](https://gateway-dev.theric.link/api/upload/chunk): Uploads a file chunk (5MB recommended)
- [POST /api/upload/finalize](https://gateway-dev.theric.link/api/upload/finalize): Completes upload and creates draft content/media records
- [POST /api/content/{did}/publish](https://gateway-dev.theric.link/api/content/{did}/publish): Publishes draft content to OCME Registry (creates DID documents, transitions draft → registered)

## Integration

- [Claude Code Prompts](https://gateway-dev.theric.link/#prompts): Ready-to-use prompts for building CreatorCubiCube features with Claude Code
- [Architecture Diagram](https://gateway-dev.theric.link/#integration): Visual overview of how CreatorCubiCubes connect to RIC Gateway

## Authentication

All API requests require a JWT token in the Authorization header:

```
Authorization: Bearer {token}
```

Tokens are issued by Sentinel after magic link authentication. The token contains the creator's email, which is used to scope all database queries.

## Response Format

All API responses use a consistent envelope:

```json
{
  "success": true,
  "data": { ... },
  "error": null
}
```

On error:

```json
{
  "success": false,
  "data": null,
  "error": "Error message"
}
```

## Pagination

List endpoints support pagination via query parameters:

- `limit`: Number of items per page (default: 20, max: 100)
- `offset`: Number of items to skip (default: 0)

## Optional

- [OCME Documentation](https://ocmeco.org): Learn more about the Open Commercial Media Ecosystem
- [Sentinel Auth](https://dev-sentinel.ocmeregistry.com): Passwordless authentication service for OCME