Getting started

The Zentag Partner API gives you programmatic access to clips, highlights, media,
publishing, and signed webhooks. This guide gets you from zero to your first
authenticated request in a few minutes.

1. Create a partner app and API key

In Zentag Studio, go to Settings → Partner integrations → Apps & keys:

Click New app, choose the test environment, and select the scopes you
need (e.g. clips:read, publish:write).
Open the app and click Generate key.
Copy the secret key (zt_test_sk_...). It is shown once - store it in
a secrets manager.

2. Make your first request

Authenticate with the Authorization: Bearer header:

curl https://api.zentag.app/api/v1/partner/me \
  -H "Authorization: Bearer zt_test_sk_..."

You'll get back your key's environment and scopes:

{
  "object": "api_key_context",
  "environment": "test",
  "scopes": ["clips:read", "publish:write"],
  "publishable_key": "zt_test_pk_..."
}

3. List some clips

curl "https://api.zentag.app/api/v1/partner/clips?limit=10" \
  -H "Authorization: Bearer zt_test_sk_..."

4. Generate a clip (HLS export)

curl -X POST "https://api.zentag.app/api/v1/partner/clips/generate" \
  -H "Authorization: Bearer zt_test_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"stream_id":"YOUR_STREAM_ID","start_offset_seconds":10,"end_offset_seconds":25,"source":"replay"}'

Subscribe to clip.created / clip.ready / clip.failed webhooks for the outcome.

5. Async clip AI jobs

curl -X POST "https://api.zentag.app/api/v1/partner/clips/CLIP_ID/autoflip" \
  -H "Authorization: Bearer zt_test_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"aspect_ratio":"9:16"}'

See Clips AI jobs. Highlight generate (mode: ai | manual | ai_global) works the same way with highlight.ready / highlight.failed.

6. Local smoke check

From zentag-backend_:

PARTNER_KEY=zt_test_sk_... npm run script:partner-smoke

7. Go live

When you're ready, create a live app, generate live keys (zt_live_sk_...),
and swap the credentials. Live and test data are fully isolated.