API overview

The segmnt API is a REST API. Every request and answer is JSON. Base URL: https://api.segmnt.cloud This reference covers 39 public endpoints across 30 paths. Every public endpoint has an entry in the sidebar, with its request and response shapes.

​

Authentication

There are two ways to authenticate. Rules:

• Keep the API key on your server. It can create playback tokens, so anyone with it can play your videos anywhere. Never put a key in a page, a browser or a mobile app.
• A key works only for its own project’s routes. A key from another project answers 404.
• A revoked key answers 401 immediately.
• Account routes (projects, API keys, domains, billing) accept only the session. An API key cannot manage keys, projects or domains.
• Sign-in is SSO only: Google and GitHub. We never store a password.

Full detail: Accounts, projects, API keys and domains.

​

Conventions

• IDs are strings with a type prefix: acc_, usr_, prj_, vid_, upl_, key_, dom_, whe_, evt_.
• Times are RFC 3339 in UTC.
• Pagination is by cursor. Pass the nextCursor from an answer back as cursor to get the next page.
• Errors are application/problem+json with a stable code. See Errors.
• Idempotency-Key is scoped to the account and the route. The same key with the same body returns the first result. The same key with a different body gets 422.
• Money is an integer in the smallest currency unit (halalas for SAR; 1 SAR = 100 halalas).
• Bodies are application/json. Another content type gets 415.

​

Rate limits

Over a limit you get 429 with Retry-After. See Errors.

​

The public endpoints

​

System and auth

​

Projects, keys and domains

​

Uploads and videos

​

Webhooks, usage and billing

​

Where to go next

• Quickstart — the end-to-end path, from upload to a 403 off-domain.
• Errors — every code, with the 403 and 409 causes.
• Changelog — what changed and when.
• Glossary — the words used here.