Integrate with AI

If you use an AI coding agent, you do not have to read the rest of these guides. Copy the prompt below into Claude Code, Cursor, or whatever agent you use, and it will read your project, tell you what it plans to add, ask you for your API key, and wire up upload, playback and webhooks.

It works in any language. For TypeScript and JavaScript it uses the SDK; for anything else it calls the REST API directly.

Prefer to do it by hand? Follow Getting started instead, or run the Next.js starter to see a working integration first.

The prompt

You are integrating Hyperserve video upload, transcoding and playback into this
application.

Read these first:
- Getting started: https://docs.hyperserve.io/
- Worked example, follow this structure:
  https://raw.githubusercontent.com/hyper-serve/hyperserve-nextjs-starter/main/README.md
- API reference: https://docs.hyperserve.io/api-reference/video-controller-create
- SDK reference: https://docs.hyperserve.io/sdk-reference/sdk
- Webhooks: https://docs.hyperserve.io/guides/webhooks

Start by inspecting this project: language, framework, how it serves HTTP routes,
where env vars are read from, and whether it has a browser client. Tell me what
you found and what you plan to add before you write any code.

Which client to use:
- TypeScript or JavaScript: use the @hyperserve/hyperserve-js SDK.
- Any other language: there is no SDK. Call the REST API directly, and
  authenticate every API call with an X-API-KEY header holding your key.

Ask me for my Hyperserve API key and write it to this project's env file as
HYPERSERVE_API_KEY. I can create one at https://hyperserve.io/api-keys. Never
inline it in source and never expose it to the client bundle. Add the env file to
.gitignore if it is not already there.

The upload is three calls:
1. createVideo({ filename, resolutions, isPublic }) on your server. Returns id,
   uploadUrl and contentType.
2. PUT the file to uploadUrl from the browser. In JS/TS use putVideoToStorage
   from @hyperserve/hyperserve-js/browser. The uploadUrl is presigned, so this
   one call takes no API key. If the file is already on your server with no
   browser involved (a CLI, a worker, a batch job), use uploadVideo instead:
   it wraps createVideo, the storage PUT and completeUpload into one call.
3. completeUpload(id) on your server. This queues transcoding.

Rules you must not break:
- The API key is server-side only. @hyperserve/hyperserve-js/browser is the only
  import safe to bundle.
- The Content-Type on the PUT must be exactly the contentType returned by
  createVideo, or the presigned URL rejects the request.
- Transcoding is async. createVideo returns before there is anything to play.
- To learn when a video is ready, prefer a webhook. The payload already carries a
  playable videoUrl per resolution, so store it and do not poll. Poll getVideo
  only where you cannot receive an HTTP callback, or to get a fresh signed URL for
  a private video.
- In a webhook handler, read the raw request body as text and verify the signature
  before parsing it. Parsing first breaks verification.
- Return non-2xx from your webhook handler on failure. Hyperserve retries, which
  is what you want.

Build upload and playback first and have me confirm a video plays. Then ask me
whether I want webhooks. If I do, walk me through it one step at a time and wait
for me at each step:
1. Write the webhook handler route and verify the signature against
   HYPERSERVE_WEBHOOK_SECRET. In JS/TS use verifyWebhookSignature from
   @hyperserve/hyperserve-js; the signing scheme is not something to hand-roll.
2. If I am running locally I need a public URL. Give me
   npx cloudflared tunnel --url http://localhost:PORT with my actual port, and ask
   me to paste back the URL it prints. If I am already deployed, ask me for that
   URL instead.
3. Tell me the full webhook URL to register, which is that URL plus my handler
   path, and send me to https://hyperserve.io/webhooks to create it.
4. Ask me to paste the signing secret. Write it to the env file as
   HYPERSERVE_WEBHOOK_SECRET and tell me to restart the dev server.
5. Have me upload a video, then confirm the event arrived and the signature
   verified.

When you are done, tell me how to run it and how to confirm a video uploaded and
played.

What to expect

1. It reports what it found in your project before it changes anything.
2. It asks for your API key and writes it to your env file. Create a key in the dashboard.
3. It builds upload and playback, and asks you to confirm a video plays.
4. It offers webhooks. Say yes and it walks you through the tunnel, registering the webhook, and pasting the signing secret back.