Add transcript download endpoint to REST API

[abegong]

There currently isn't a way to programmatically retrieve a video's transcript (VTT) via the Developer API or any public endpoint. The transcript data exists in S3 and is rendered in the share page UI, but it's only accessible through Next.js server actions — which can't be called externally with curl or similar tools.

Use case

I want to fetch transcripts for Cap recordings programmatically (e.g. to feed into documentation pipelines, search indexes, or note-taking workflows). Right now the only option is to open the share page in a browser and use the UI download button.

What exists today

The video object returned by GET /api/developer/v1/videos/:id already includes transcriptionStatus, but there's no endpoint to retrieve the actual transcript content.

Internally, the transcript is stored in S3 at {ownerId}/{videoId}/transcription.vtt and is fetched by the server action in apps/web/actions/videos/get-transcript.ts. The share page's Transcript tab (apps/web/app/s/[videoId]/_components/tabs/Transcript.tsx) consumes it via the useTranscript hook.

There is a code path in apps/web/app/api/playlist/route.ts that serves VTT when fileType=transcription is passed — but it's only reachable for videos stored in a custom S3 bucket, since the Option.isNone(customBucket) branch returns early with a redirect before the fileType check.

Proposal

Add a GET /api/developer/v1/videos/:id/transcript endpoint that returns the VTT content. Something like:

GET /api/developer/v1/videos/:id/transcript
Authorization: Bearer csk_...

200 OK
Content-Type: text/vtt

WEBVTT

1
00:00:01.000 --> 00:00:04.000
Hello, this is my recording...

Returning 404 when transcriptionStatus is not COMPLETE, and 202 if it's still PROCESSING.

This would follow the existing pattern in apps/web/app/api/developer/v1/[...route]/videos.ts and use the same S3Buckets.getBucketAccess + bucket.getObject approach that get-transcript.ts already uses.

A secondary (smaller) fix would be to also make the existing /api/playlist?videoId=...&fileType=transcription path work for default-bucket videos, not just custom-bucket ones.

Willingness to contribute

I'm happy to write the code for this if it's something you'd accept as a PR. Let me know if this aligns with your plans or if there's a preferred approach.

[linear]

CAP-658

[tembo]

Your analysis of the codebase is spot on. Here's some additional context that might help with implementation:

Developer API structure

The endpoint would go in apps/web/app/api/developer/v1/[...route]/videos.ts. The existing endpoints follow a straightforward Hono pattern with withDeveloperSecretAuth middleware already applied. The /:id/status endpoint (lines 91-125) is a good template since it already queries transcriptionStatus.

S3 access for developer videos

One consideration: the developerVideos table has its own s3Key column but doesn't track a bucket reference the way the main videos table does. You'll need to determine how developer video transcripts are stored. Looking at the schema in packages/database/schema.ts around line 960, developer videos may use a different S3 path convention than regular videos.

The get-transcript.ts server action fetches from ${video.ownerId}/${videoId}/transcription.vtt using the video's associated bucket. For developer videos, you'll likely need to use the app's default storage or check if there's a bucket association.

Response status codes

Your proposed status codes make sense:

• 200 with VTT content when transcriptionStatus === "COMPLETE"
• 404 when video not found
• 202 Accepted when transcriptionStatus === "PROCESSING" (good pattern for async workflows)
• Consider 204 No Content or a specific error for NO_AUDIO / SKIPPED / ERROR states

Implementation snippet pattern

app.get("/:id/transcript", async (c) => {
  const appId = c.get("developerAppId");
  const videoId = c.req.param("id");
  
  const [video] = await db()
    .select()
    .from(developerVideos)
    .where(and(
      eq(developerVideos.id, videoId),
      eq(developerVideos.appId, appId),
      isNull(developerVideos.deletedAt),
    ))
    .limit(1);

  if (!video) {
    return c.json({ error: "Video not found" }, 404);
  }

  if (video.transcriptionStatus === "PROCESSING") {
    return c.json({ error: "Transcript still processing" }, 202);
  }

  if (video.transcriptionStatus !== "COMPLETE") {
    return c.json({ error: "No transcript available", status: video.transcriptionStatus }, 400);
  }

  // Fetch from S3 - pattern depends on how developer video storage is configured
  // ...
  
  return c.text(vttContent, 200, {
    "Content-Type": "text/vtt",
    "Cache-Control": "no-store",
  });
});

Re: the /api/playlist fix

You're right that the Option.isNone(customBucket) branch returns early before reaching the fileType check. That fix would be in apps/web/app/api/playlist/route.ts and would involve restructuring the branching logic so the transcription fetch happens before the early return. However, that route is unauthenticated and designed for public share pages, so it might be better suited as a separate change.

Looks like a solid contribution - the developer API could definitely use this.

[abegong]

So should I go ahead and make the contribution? Or should I wait for a human on the team to weigh in?