Apps

An App represents an isolated project or environment within an Organization. Each app has its own API keys, origins, presets, and jobs, making it easy to separate production from staging, or to run multiple independent products under a single billing entity.

Overview

Apps provide resource isolation within an organization. A typical setup might look like:

Acme Corporation (org)
  ├── Production (app) — live API keys, production origins
  ├── Staging (app)    — test API keys, staging origins
  └── Analytics (app)  — separate project with its own config

Creating an App

Create an app inside an organization by passing its org_id and a name; a description is optional. App names must be unique within the organization (case-insensitive) and are limited to 60 characters.

curl -X POST https://api.transcodely.com/transcodely.v1.AppService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "org_id": "org_a1b2c3d4e5",
    "name": "Production",
    "description": "Live video transcoding for our streaming platform"
  }'

const app = await client.apps.create({
  orgId: "org_a1b2c3d4e5",
  name: "Production",
  description: "Live video transcoding for our streaming platform",
});

app = client.apps.create(
    org_id="org_a1b2c3d4e5",
    name="Production",
    description="Live video transcoding for our streaming platform",
)

app, err := client.Apps.Create(ctx, &transcodely.AppCreateParams{
	OrgId:       "org_a1b2c3d4e5",
	Name:        "Production",
	Description: proto.String("Live video transcoding for our streaming platform"),
})

{
  "app": {
    "id": "app_k1l2m3n4o5",
    "org_id": "org_a1b2c3d4e5",
    "name": "Production",
    "description": "Live video transcoding for our streaming platform",
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

App Status

Status	Description	Behavior
`active`	Normal operation	Full access to all resources
`archived`	Soft-deleted	No new resources can be created; existing jobs continue to completion

Archive an app when you no longer need it. Existing jobs will finish processing, but no new jobs, API keys, or origins can be created.

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

const app = await client.apps.archive("app_k1l2m3n4o5");

app = client.apps.archive("app_k1l2m3n4o5")

err := client.Apps.Archive(ctx, "app_k1l2m3n4o5")

Video Hosting

Apps can opt in to managed video hosting. Transcodely provisions a storage bucket and CDN for the app, so transcoded outputs are served from a *.b-cdn.net hostname without you wiring up your own origin. Enabling hosting is a one-way operation — once on, it cannot be turned off.

Enable hosting when creating an app by setting enable_hosting: true, or enable it later with the EnableHosting RPC:

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

const { app } = await client.apps.enableHosting({ id: "app_k1l2m3n4o5" });

res = client.apps.enable_hosting(id="app_k1l2m3n4o5")
app = res.app

app, err := client.Apps.EnableHosting(ctx, "app_k1l2m3n4o5")

Once hosting is enabled, the App object carries these read-only fields:

Field	Type	Description
`hosting_enabled`	`bool`	`true` once hosting has been enabled for the app.
`hosting_status`	`string`	Hosting readiness: `active`, `provisioning`, or `not_configured`.
`cdn_hostname`	`string`	CDN hostname (e.g. `transcodely-app-xxx.b-cdn.net`). Only set once hosting is active.
`hosting_config`	`object`	The app’s hosting configuration (see below). Only set when `hosting_enabled` is `true`.

Hosting configuration

Tune delivery, upload limits, and auto-transcoding defaults with UpdateHostingConfig. Provided fields are merged into the existing config; the call returns failed_precondition if hosting has not been enabled.

Field	Type	Description
`default_visibility`	`string`	Default visibility for new uploads: `public`, `unlisted`, or `private`.
`max_upload_size_bytes`	`int64`	Maximum upload file size in bytes (`0` means no limit).
`cors_allowed_origins`	`string[]`	Domains allowed to embed or fetch videos from the CDN. Transcodely’s player base URL is always included automatically.
`auto_profile_defaults`	`object`	Default transcoding settings (`format`, `codec`, `max_resolution`, `quality_tier`, `encoding_mode`) applied when an upload specifies no preset.

curl -X POST https://api.transcodely.com/transcodely.v1.AppService/UpdateHostingConfig 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "id": "app_k1l2m3n4o5",
    "hosting_config": {
      "default_visibility": "unlisted",
      "max_upload_size_bytes": 5368709120,
      "cors_allowed_origins": ["https://app.example.com"]
    }
  }'

const { app } = await client.apps.updateHostingConfig({
  id: "app_k1l2m3n4o5",
  hostingConfig: {
    defaultVisibility: "unlisted",
    maxUploadSizeBytes: 5368709120n,
    corsAllowedOrigins: ["https://app.example.com"],
  },
});

res = client.apps.update_hosting_config(
    id="app_k1l2m3n4o5",
    hosting_config={
        "default_visibility": "unlisted",
        "max_upload_size_bytes": 5368709120,
        "cors_allowed_origins": ["https://app.example.com"],
    },
)

app, err := client.Apps.UpdateHostingConfig(ctx, &transcodely.AppUpdateHostingConfigParams{
	Id: "app_k1l2m3n4o5",
	HostingConfig: &transcodely.HostingConfig{
		DefaultVisibility:  proto.String("unlisted"),
		MaxUploadSizeBytes: proto.Int64(5368709120),
		CorsAllowedOrigins: []string{"https://app.example.com"},
	},
})

A full video hosting guide — uploads, players, and auto_profile_defaults — is coming soon.

Webhooks

Removed: The legacy app-level webhook field has been removed from the API. Use the WebhookService instead — it supports multiple signed endpoints per app, HMAC-SHA-256 signing with secret rotation, per-event-type subscriptions, delivery history, and health metrics. Existing per-app webhook configurations were migrated to WebhookService endpoints automatically. Any request that still sets webhook (on Create, Update, and related calls) is silently ignored rather than rejected, so remove it from your payloads.

Manage webhook endpoints for an app in the Webhooks dashboard, via the WebhookService API, or with the official SDKs (e.g. client.webhookEndpoints.create({ appId, url, enabledEvents })). For an end-to-end walkthrough — creating an endpoint, verifying signatures, and handling events — see the Webhook Integration guide.

Listing Apps

List the apps in an organization, optionally including archived ones. Results are paginated, and the SDKs auto-page so you can iterate every app without juggling page tokens.

curl -X POST https://api.transcodely.com/transcodely.v1.AppService/List 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "org_id": "org_a1b2c3d4e5",
    "pagination": { "limit": 20 },
    "include_archived": false
  }'

for await (const app of client.apps.list({
  orgId: "org_a1b2c3d4e5",
  pagination: { limit: 20 },
  includeArchived: false,
}).autoPage()) {
  console.log(app.id, app.name);
}

for app in client.apps.list(
    org_id="org_a1b2c3d4e5",
    limit=20,
    include_archived=False,
).auto_paging_iter():
    print(app.id, app.name)

iter := client.Apps.List(ctx, &transcodely.AppListParams{
	OrgId:           "org_a1b2c3d4e5",
	Pagination:      &transcodely.PaginationRequest{Limit: 20},
	IncludeArchived: false,
})
for iter.Next() {
	app := iter.Current()
	fmt.Println(app.GetId(), app.GetName())
}
if err := iter.Err(); err != nil {
	log.Fatal(err)
}

#Apps

#Overview

#Creating an App

#App Status

#Video Hosting

#Hosting configuration

#Webhooks

#Listing Apps