# ReplyCam API

Base URL: `https://replycam.com`

OpenAPI JSON: `https://replycam.com/api/openapi.json`

Markdown docs: `https://replycam.com/api/docs.md`

These docs are for project creators who already have an API token.

In plain English: create a project, get recording links, send those links to people, then fetch the videos, transcripts, and exports later with the returned project ID.

## Quick Start

1. Call `GET /api/me` once to confirm the token works.
2. Call `POST /api/projects` to create a project and generate links.
3. Send the returned `recipientUrls` or shared link to contributors.
4. Use `projectId` with `/links`, `/submissions`, or the export routes to retrieve the results later.

## End-to-End Example

### Step 1. Confirm the token

```bash
curl https://replycam.com/api/me \
  -H 'authorization: Bearer api_...'
```

### Step 2. Create the project

Save the returned `projectId`, `dashboardUrl`, and any recipient URLs you plan to send.

```bash
curl -X POST https://replycam.com/api/projects \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer api_...' \
  -d '{
    "projectName": "Customer Testimonial Round",
    "count": 12,
    "expiresInHours": 72,
    "neverExpire": false,
    "sharedLinkEnabled": true,
    "sharedLinkMaxUses": 1000,
    "maxDurationSec": 180,
    "transcriptionEnabled": true,
    "noteEnabled": false,
    "requestUrl": "https://example.com/brief",
    "interviewQuestions": [
      "What problem were you trying to solve?",
      "What changed after using it?"
    ],
    "webhookUrl": "https://example.com/replycam/webhooks",
    "webhookSecret": "replace-with-your-secret",
    "requireTerms": true,
    "showSuccessDialog": true
  }'
```

### Step 3. Pull the links later

```bash
curl https://replycam.com/api/projects/PROJECT_ID/links \
  -H 'authorization: Bearer api_...'
```

### Step 4. Fetch submissions and transcripts

```bash
curl 'https://replycam.com/api/projects/PROJECT_ID/submissions?limit=25&selected=true&transcriptStatus=completed' \
  -H 'authorization: Bearer api_...'
```

## Auth Model

- Admin provisioning: internal-only controls for minting users and scoped tokens
- Creator API: Bearer-token API for creating and retrieving projects
- Project dashboard token: private URL token for read-only dashboard exports and QR PNG routes
- Recipient token: recording-only link at `/r/vr_...`

## Authentication

Send your API token as a Bearer token on each request.

```
Authorization: Bearer api_...
```

## Token Scopes

- `profile:read` for `GET /api/me`
- `projects:read` for project listing and project detail
- `projects:write` for project creation and updates
- `links:read` for recipient links
- `submissions:read` for submissions, transcripts, and media

## Check Your Token

`GET /api/me`

```bash
curl https://replycam.com/api/me \
  -H 'authorization: Bearer api_...'
```

## Create A Project

`POST /api/projects`

```bash
curl -X POST https://replycam.com/api/projects \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer api_...' \
  -d '{
    "projectName": "Customer Testimonial Round",
    "count": 12,
    "expiresInHours": 72,
    "neverExpire": false,
    "sharedLinkEnabled": true,
    "sharedLinkMaxUses": 1000,
    "maxDurationSec": 180,
    "transcriptionEnabled": true,
    "noteEnabled": false,
    "requestUrl": "https://example.com/brief",
    "interviewQuestions": [
      "What problem were you trying to solve?",
      "What changed after using it?"
    ],
    "webhookUrl": "https://example.com/replycam/webhooks",
    "webhookSecret": "replace-with-your-secret",
    "requireTerms": true,
    "showSuccessDialog": true
  }'
```

## Update A Project

`PATCH /api/projects/PROJECT_ID`

```bash
curl -X PATCH https://replycam.com/api/projects/PROJECT_ID \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer api_...' \
  -d '{
    "projectName": "Customer Testimonial Round / Wave 2",
    "expiresInHours": 168,
    "sharedLinkMaxUses": 1500,
    "transcriptionEnabled": true,
    "noteEnabled": true,
    "requestUrl": "https://example.com/brief-v2",
    "interviewQuestions": [
      "Tell me what stood out most.",
      "Who would you recommend it to?"
    ],
    "requireTerms": true,
    "termsLabel": "I authorize the use of my content and agree to the terms.",
    "showSuccessDialog": true,
    "successMessage": "Thanks. You may close this page."
  }'
```

## List Projects

`GET /api/projects`

```bash
curl https://replycam.com/api/projects \
  -H 'authorization: Bearer api_...'
```

## Project Detail

`GET /api/projects/PROJECT_ID`

```bash
curl https://replycam.com/api/projects/PROJECT_ID \
  -H 'authorization: Bearer api_...'
```

## Project Links

`GET /api/projects/PROJECT_ID/links`

```bash
curl https://replycam.com/api/projects/PROJECT_ID/links \
  -H 'authorization: Bearer api_...'
```

## Interview Mode

- Set `interviewQuestions` to an ordered array when one contributor should answer multiple prompts in sequence.
- Set `requestUrl` when contributors should be able to open a supporting page, brief, or example while recording.
- Each answer is stored as its own submission.
- Use `responseSessionId` to keep one contributor’s answers grouped together.
- Use `questionIndex` and `questionText` on each submission for question-level sorting, exports, and analysis.
- After the final interview answer uploads, the contributor is sent to a dedicated thank-you page.

## Shared Link QR PNG

`GET /api/projects/PROJECT_ID/shared-link/qr.png`

```bash
curl https://replycam.com/api/projects/PROJECT_ID/shared-link/qr.png \
  -H 'authorization: Bearer api_...' \
  --output shared-link-qr.png
```

## Dashboard Token Routes

Use these when you have the private project dashboard URL or `projectToken`, not a creator Bearer token.

- `GET /project/PROJECT_TOKEN/export.json`
- `GET /project/PROJECT_TOKEN/export.csv`
- `GET /project/PROJECT_TOKEN/export/project.zip`
- `GET /project/PROJECT_TOKEN/export/transcripts.txt`
- `GET /project/PROJECT_TOKEN/shared-link/qr.png`

## Project Submissions

`GET /api/projects/PROJECT_ID/submissions`

```bash
curl 'https://replycam.com/api/projects/PROJECT_ID/submissions?limit=25&selected=true&transcriptStatus=completed' \
  -H 'authorization: Bearer api_...'
```

Supports:

- `limit`
- `cursor`
- `selected=true|false`
- `transcriptStatus=pending|processing|completed|failed|disabled`

## Project Exports

`GET /api/projects/PROJECT_ID/export.json`

```bash
curl https://replycam.com/api/projects/PROJECT_ID/export.json \
  -H 'authorization: Bearer api_...'
```

`GET /api/projects/PROJECT_ID/export.csv`

```bash
curl https://replycam.com/api/projects/PROJECT_ID/export.csv \
  -H 'authorization: Bearer api_...' \
  --output replycam-submissions.csv
```

`GET /api/projects/PROJECT_ID/export/project.zip`

```bash
curl https://replycam.com/api/projects/PROJECT_ID/export/project.zip \
  -H 'authorization: Bearer api_...' \
  --output replycam-project.zip
```

`GET /api/projects/PROJECT_ID/export/transcripts.txt`

```bash
curl 'https://replycam.com/api/projects/PROJECT_ID/export/transcripts.txt?selected=true' \
  -H 'authorization: Bearer api_...' \
  --output replycam-transcripts.txt
```

## Transcript Downloads

- `GET /api/projects/PROJECT_ID/submissions/SUBMISSION_ID/transcript.txt`
- `GET /api/projects/PROJECT_ID/submissions/SUBMISSION_ID/transcript.vtt`

## Webhooks

- Optional project settings: `webhookUrl`, `webhookSecret`
- Event types:
  - `submission.completed`
  - `submission.transcript.completed`
  - `submission.transcript.failed`
- Headers:
  - `replycam-event`
  - `replycam-event-id`
  - `replycam-signature`

## Media Endpoints

- `GET /api/projects/PROJECT_ID/submissions/SUBMISSION_ID/video`
- `GET /api/projects/PROJECT_ID/submissions/SUBMISSION_ID/thumbnail-start`
- `GET /api/projects/PROJECT_ID/submissions/SUBMISSION_ID/thumbnail-middle`
- `GET /api/projects/PROJECT_ID/submissions/SUBMISSION_ID/thumbnail-end`
- `GET /api/projects/PROJECT_ID/submissions/SUBMISSION_ID/audio`

## Useful Fields

- `projectId`: stable project identifier
- `videosCreated`: completed submissions so far
- `responseSlotsRemaining`: total remaining response capacity
- `recipientUrl`: recording link you send to responders
- `videoUrl`: authenticated media URL
- `responseSessionId`: stable session ID for one contributor across multiple interview answers
- `questionIndex`: zero-based question position on interview submissions
- `questionText`: prompt text attached to that answer
- `transcriptText`: completed transcript text
- `reviewNote`: reviewer note saved from the dashboard and included in exports
- `transcriptTextUrl`: plain-text transcript download endpoint
- `transcriptVttUrl`: VTT transcript download endpoint
- `nextCursor`: opaque cursor for the next submissions page
- `selected`: dashboard reviewer selection state
- `webhookEnabled`: whether the project pushes webhook events

## Usage Limits

- Your token may have a project or video creation allowance attached to it.
- Shared links count toward that allowance based on their maximum use count.
- ReplyCam currently supports clips up to 600 seconds (10 minutes).
- ReplyCam also enforces generous runtime rate limits and returns HTTP 429 if one route is hit far too aggressively.

## Agent Notes

- Prefer `projectId` and `submissionId` as canonical IDs.
- Prefer `https://replycam.com/api/openapi.json` first when a tool or agent can ingest OpenAPI.
- Use `https://replycam.com/api/docs.md` when you want markdown instead of HTML.
- Repository skill: `.agents/skills/replycam-api/SKILL.md`
- Skill metadata: `.agents/skills/replycam-api/agents/openai.yaml`
- If the user only gives you a project dashboard URL, use the dashboard-token routes for exports and QR PNGs.
- For interview projects, preserve `responseSessionId`, `questionIndex`, and `questionText` when syncing or exporting responses.
- Typical sync loop:
  1. list projects
  2. fetch one project by `projectId`
  3. fetch `/links` or page through `/submissions`
  4. fetch media URLs as needed