#Core Concepts

Transcodely is built around a small set of composable resources. Understanding how they relate to each other is the key to integrating effectively.

#Entity Hierarchy

Every resource in Transcodely lives within a clear ownership hierarchy:

Organization (billing entity)
  └── App (project / environment)
        ├── API Keys (authentication credentials)
        ├── Origins (storage locations)
        ├── Presets (encoding templates)
        └── Jobs (transcoding work)

Organizations are the top-level billing entity. They hold one or more Apps, which act as isolated projects or environments (e.g., Production, Staging). All resources — API keys, storage origins, presets, and jobs — are scoped to a single app.

#How the Pieces Fit Together

A typical integration follows this flow:

1. Create an Organization — your billing entity with a unique slug
2. Create an App — a project within the org (e.g., “My Video Platform”)
3. Create API Keys — generate ak_live_ and ak_test_ keys for authentication
4. Configure Origins — connect your GCS, S3, or HTTP storage for inputs and outputs
5. Set up Presets — define reusable encoding configurations, or use system presets
6. Submit Jobs — send transcoding requests that reference your origins and presets

#Authentication Model

All API requests require an API key passed as a Bearer token. Organization-scoped endpoints also require the X-Organization-ID header:

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{ ... }'

#Resource Identifiers

Every resource has a globally unique, prefixed identifier that tells you what type of object it is at a glance:

IDs are stable and permanent. They never change and can safely be stored in your database.

#API Protocol

Transcodely uses Connect-RPC with JSON encoding. Every endpoint accepts POST requests with Content-Type: application/json. Endpoints follow the pattern:

POST /transcodely.v1.{Service}/{Method}

For example:

• POST /transcodely.v1.JobService/Create
• POST /transcodely.v1.PresetService/List
• POST /transcodely.v1.OriginService/Validate

#What’s Next

Explore each concept in depth:

• Organizations — billing entities and team management
• Apps — project isolation and webhook configuration
• API Keys — authentication and environment separation
• Origins — storage providers for video inputs and outputs
• Presets — reusable encoding configurations
• Jobs — the transcoding lifecycle from submission to completion
• Webhooks — real-time event notifications
• Pricing — how encoding costs are calculated