The App object

Apps are projects within an organization. Each app has its own API keys, jobs, origins, presets, and webhook endpoints. Use apps to separate environments (production, staging) or different products.

Base path: transcodely.v1.AppService Requires: X-Organization-ID header on all endpoints.

Attributes

Attribute	Type	Description
`id`	string	Unique identifier. Prefixed with `app_`.
`org_id`	string	Parent organization ID.
`name`	string	Display name.
`description`	string	Description. Omitted if not set.
`status`	enum	One of: `active`, `archived`.
`created_at`	string	ISO 8601 timestamp.
`updated_at`	string	ISO 8601 timestamp.
`archived_at`	string	ISO 8601 timestamp. Omitted if not archived.
`hosting_enabled`	boolean	Whether managed video hosting is enabled for this app. Omitted if not set.
`hosting_status`	string	Hosting readiness. One of: `active`, `provisioning`, `not_configured`.
`cdn_hostname`	string	CDN hostname for delivered videos (e.g., `transcodely-app-xxx.b-cdn.net`). Only set when hosting is active.
`hosting_config`	object	Hosting configuration. Only set when hosting is enabled. See Update hosting configuration.
`monthly_spend_limit_eur`	number	Monthly cap on transcoding charges, in EUR. Omitted when unlimited (the default). Set or clear it with Set the spend limit; read current spend with Get current spend.
`player_config`	object	Hosted player configuration. Omitted until configured. See Update player configuration.
`object`	string	Resource type. Always `"app"`.

{
  "id": "app_k1l2m3n4o5",
  "object": "app",
  "org_id": "org_f6g7h8i9j0",
  "name": "Production",
  "description": "Production video processing",
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

App-level webhooks have been removed. The legacy per-app webhook config — along with the generate_secret / regenerate_secret flags that used to appear on Create and Update — no longer exists on the wire. Register signed endpoints with the WebhookService instead, which supports multiple endpoints per app, HMAC-SHA-256 signing with rotation, per-event subscriptions, delivery history, and health metrics. See the Webhook Integration guide.

Create an app

Create a new app within an organization.

POST /transcodely.v1.AppService/Create

Parameters

Parameter	Type	Required	Description
`org_id`	string	Yes	Parent organization ID (e.g., `"org_f6g7h8i9j0"`).
`name`	string	Yes	Display name (1-60 chars). Must be unique within the organization (case-insensitive).
`description`	string	No	Optional description (max 500 chars).
`enable_hosting`	boolean	No	Provision managed video hosting (CDN) infrastructure for the app on creation. Defaults to `false`. Cannot be disabled once enabled.

Returns

Returns an App object.

curl -X POST https://api.transcodely.com/transcodely.v1.AppService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{
    "org_id": "org_f6g7h8i9j0",
    "name": "Production",
    "description": "Production video processing"
  }'

const app = await client.apps.create({
  orgId: "org_f6g7h8i9j0",
  name: "Production",
  description: "Production video processing",
});

app = client.apps.create(
    org_id="org_f6g7h8i9j0",
    name="Production",
    description="Production video processing",
)

app, err := client.Apps.Create(ctx, &transcodely.AppCreateParams{
	OrgId:       "org_f6g7h8i9j0",
	Name:        "Production",
	Description: proto.String("Production video processing"),
})

{
  "app": {
    "id": "app_k1l2m3n4o5",
    "object": "app",
    "org_id": "org_f6g7h8i9j0",
    "name": "Production",
    "description": "Production video processing",
    "status": "active",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Retrieve an app

Retrieve an app by its ID.

POST /transcodely.v1.AppService/Get

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	App ID (e.g., `"app_k1l2m3n4o5"`).

Returns

Returns an App object.

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

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

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

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

{
  "app": {
    "id": "app_k1l2m3n4o5",
    "object": "app",
    "org_id": "org_f6g7h8i9j0",
    "name": "Production",
    "description": "Production video processing",
    "status": "active",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Update an app

Update an app’s name and description.

POST /transcodely.v1.AppService/Update

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	App ID.
`name`	string	No	New display name (1-60 chars).
`description`	string	No	New description (max 500 chars).

Returns

Returns the updated App object.

curl -X POST https://api.transcodely.com/transcodely.v1.AppService/Update 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{
    "id": "app_k1l2m3n4o5",
    "name": "Production (v2)"
  }'

const app = await client.apps.update({
  id: "app_k1l2m3n4o5",
  name: "Production (v2)",
});

app = client.apps.update(
    id="app_k1l2m3n4o5",
    name="Production (v2)",
)

app, err := client.Apps.Update(ctx, &transcodely.AppUpdateParams{
	Id:   "app_k1l2m3n4o5",
	Name: proto.String("Production (v2)"),
})

{
  "app": {
    "id": "app_k1l2m3n4o5",
    "object": "app",
    "org_id": "org_f6g7h8i9j0",
    "name": "Production (v2)",
    "description": "Production video processing",
    "status": "active",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-02-28T15:00:00Z"
  }
}

List apps

List apps within an organization.

POST /transcodely.v1.AppService/List

Parameters

Parameter	Type	Required	Description
`org_id`	string	Yes	Organization ID.
`pagination`	object	No	Pagination parameters. See API Reference overview.
`include_archived`	boolean	No	If `true`, include archived apps. Default: `false`.

Returns

Returns a list of App objects and pagination metadata.

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

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

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

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

{
  "apps": [
    {
      "id": "app_k1l2m3n4o5",
      "object": "app",
      "org_id": "org_f6g7h8i9j0",
      "name": "Production",
      "description": "Production video processing",
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "",
    "total_count": 1
  }
}

Archive an app

Soft-delete an app. Archived apps cannot create new resources, but existing jobs continue processing.

POST /transcodely.v1.AppService/Archive

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	App ID.

Returns

Returns the App object with status: "archived".

curl -X POST https://api.transcodely.com/transcodely.v1.AppService/Archive 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -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")

{
  "app": {
    "id": "app_k1l2m3n4o5",
    "object": "app",
    "org_id": "org_f6g7h8i9j0",
    "name": "Production",
    "status": "archived",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-02-28T15:00:00Z",
    "archived_at": "2025-02-28T15:00:00Z"
  }
}

Enable hosting

Turn on managed video hosting for an app. This provisions a managed storage bucket and prepares CDN infrastructure for delivering transcoded output.

This is a one-way operation — once hosting is enabled it cannot be disabled.

POST /transcodely.v1.AppService/EnableHosting

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	App ID (e.g., `"app_k1l2m3n4o5"`).

Returns

Returns the App object with hosting_enabled: true. Immediately after enabling, hosting_status is provisioning; it becomes active once the CDN is ready and cdn_hostname is assigned.

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

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

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

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

{
  "app": {
    "id": "app_k1l2m3n4o5",
    "object": "app",
    "org_id": "org_f6g7h8i9j0",
    "name": "Production",
    "status": "active",
    "hosting_enabled": true,
    "hosting_status": "provisioning",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-02-28T15:00:00Z"
  }
}

Update hosting configuration

Update an app’s hosting configuration. Only the fields you provide are merged into the existing config; omitted fields are left unchanged. Hosting must already be enabled — this returns failed_precondition if it is not.

POST /transcodely.v1.AppService/UpdateHostingConfig

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	App ID.
`hosting_config`	object	Yes	Hosting configuration to merge. See fields below.

The hosting_config object:

Field	Type	Description
`default_visibility`	string	Default visibility for new uploads. One of: `public`, `unlisted`, `private`.
`max_upload_size_bytes`	integer	Maximum upload file size in bytes (`0` = no limit).
`cors_allowed_origins`	string[]	Domains allowed to embed or fetch videos from the CDN. System defaults (the player base URL) are always included.
`delete_source_after_days`	integer	Delete each hosted video’s original uploaded source file this many days after it becomes ready (`0` or absent = disabled; max `3650`). Only the master upload is removed — renditions and playback are unaffected. A `video.source_scheduled_for_deletion` webhook fires at least 72 hours before each deletion. See the Source Lifecycle guide.
`auto_profile_defaults`	object	Auto-transcoding defaults applied when an upload does not name a preset. See fields below.

The auto_profile_defaults object:

Field	Type	Description
`format`	string	Output format. One of: `hls`, `dash`, `mp4`.
`codec`	string	Video codec. One of: `h264`, `h265`, `vp9`, `av1`.
`max_resolution`	string	Maximum output resolution. One of: `480p`, `720p`, `1080p`, `1440p`, `2160p`.
`quality_tier`	string	Quality tier. One of: `economy`, `standard`, `premium`.
`encoding_mode`	string	Encoding mode. One of: `fixed` (static CRF) or `auto` (input-aware constrained CRF).

Returns

Returns the updated App object with the merged hosting_config.

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

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

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

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

{
  "app": {
    "id": "app_k1l2m3n4o5",
    "object": "app",
    "org_id": "org_f6g7h8i9j0",
    "name": "Production",
    "status": "active",
    "hosting_enabled": true,
    "hosting_status": "active",
    "cdn_hostname": "transcodely-app-k1l2m3n4o5.b-cdn.net",
    "hosting_config": {
      "default_visibility": "unlisted",
      "cors_allowed_origins": ["https://example.com"]
    },
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-02-28T15:00:00Z"
  }
}

Update player configuration

Merge fields into the app’s hosted-player configuration. Applies to the player page and every embed for the app’s hosted videos. Unlike hosting configuration, this works before hosting is enabled — you can stage player settings ahead of the first upload. A portal user must be an organization Owner or Admin; an API key may change only its own app’s configuration.

Currently the configuration covers caption rendering: cue background color and opacity, text color, and a text-size multiplier. Fields you omit keep their stored value; sending an empty string for a color clears it back to the player default.

POST /transcodely.v1.AppService/UpdatePlayerConfig

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	App ID (e.g., `"app_k1l2m3n4o5"`).
`player_config.captions.background_color`	string	No	Cue box background as 6-digit hex (e.g., `"#0a0a0a"`). Empty string clears back to the default (`#0a0a0a`).
`player_config.captions.background_opacity`	number	No	Cue box background opacity, `0`–`1`. Default `0.7`.
`player_config.captions.text_color`	string	No	Caption text color as 6-digit hex. Empty string clears back to the default (`#ffffff`).
`player_config.captions.font_scale`	number	No	Caption text-size multiplier, `0.5`–`2`. Default `1`.

Returns

Returns the updated App object. player_config reflects the merged configuration, or is omitted when everything is at the player defaults.

curl -X POST https://api.transcodely.com/transcodely.v1.AppService/UpdatePlayerConfig 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{
    "id": "app_k1l2m3n4o5",
    "player_config": {
      "captions": {
        "background_color": "#101820",
        "background_opacity": 0.55,
        "font_scale": 1.2
      }
    }
  }'

{
  "app": {
    "id": "app_k1l2m3n4o5",
    "object": "app",
    "org_id": "org_f6g7h8i9j0",
    "name": "Production",
    "status": "active",
    "player_config": {
      "captions": {
        "background_color": "#101820",
        "background_opacity": 0.55,
        "font_scale": 1.2
      }
    },
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-02-28T15:00:00Z"
  }
}

Set the spend limit

Set or clear an app’s monthly cap on transcoding charges, in EUR. Providing monthly_spend_limit_eur (must be > 0 and finite — NaN/Inf are rejected) sets the cap; omitting it clears the cap and returns the app to unlimited (the default). A portal user must be an organization Owner or Admin; an API key may change only its own app’s limit (a mismatched app_id is rejected — a leaked key can lift its own cap, so rotate compromised keys). See Spend limits for how spend is counted and enforced (it is a create-time guardrail, not an exact ceiling).

POST /transcodely.v1.AppService/UpdateSpendLimit

Parameters

Parameter	Type	Required	Description
`app_id`	string	Yes	App ID (e.g., `"app_k1l2m3n4o5"`).
`monthly_spend_limit_eur`	number	No	The cap in EUR (`> 0`, finite). Present sets the cap; absent clears it (back to unlimited).

Returns

Returns the updated App object. monthly_spend_limit_eur reflects the new value, or is omitted when the limit was cleared.

# Set a €500/month cap
curl -X POST https://api.transcodely.com/transcodely.v1.AppService/UpdateSpendLimit 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{
    "app_id": "app_k1l2m3n4o5",
    "monthly_spend_limit_eur": 500
  }'

# Clear the cap (omit the field) — back to unlimited
curl -X POST https://api.transcodely.com/transcodely.v1.AppService/UpdateSpendLimit 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{"app_id": "app_k1l2m3n4o5"}'

{
  "app": {
    "id": "app_k1l2m3n4o5",
    "object": "app",
    "org_id": "org_f6g7h8i9j0",
    "name": "Production",
    "status": "active",
    "monthly_spend_limit_eur": 500,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-02-28T15:00:00Z"
  }
}

Get current spend

Read an app’s transcoding spend for the current billing period, against its limit. Spend is the sum of billed charges for terminal jobs plus recorded estimates for in-flight jobs, including each job’s processing fee; jobs are attributed to the period by their creation time. Requires organization membership (same authorization as Retrieve an app).

POST /transcodely.v1.AppService/GetSpend

Parameters

Parameter	Type	Required	Description
`app_id`	string	Yes	App ID (e.g., `"app_k1l2m3n4o5"`).

Returns

Returns the current-period spend.

Field	Type	Description
`period_start`	string	Start of the current billing period (inclusive), UTC. Follows the app’s billing anchor day.
`period_end`	string	End of the current billing period (exclusive), UTC.
`spent_eur`	number	Transcoding spend recorded so far this period, in EUR.
`monthly_spend_limit_eur`	number	The app’s monthly limit in EUR. Omitted when unlimited.
`currency`	string	Currency of all amounts. Always `"EUR"`.
`warning_triggered`	boolean	`true` once the 80% warning event (`app.spend_limit_warning`) has fired this period.
`limit_reached`	boolean	`true` once the breach event (`app.spend_limit_exceeded`) has fired this period.

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

{
  "period_start": "2026-07-01T00:00:00Z",
  "period_end": "2026-08-01T00:00:00Z",
  "spent_eur": 85.5,
  "monthly_spend_limit_eur": 100,
  "currency": "EUR",
  "warning_triggered": true,
  "limit_reached": false
}

Once recorded spend reaches the limit, new jobs are rejected with Connect code resource_exhausted and error code limit_exceeded; in-flight jobs are never stopped. See Spend limits.

#The App object

#Attributes

#Create an app

#Parameters

#Returns

#Retrieve an app

#Parameters

#Returns

#Update an app

#Parameters

#Returns

#List apps

#Parameters

#Returns

#Archive an app

#Parameters

#Returns

#Enable hosting

#Parameters

#Returns

#Update hosting configuration

#Parameters

#Returns

#Update player configuration

#Parameters

#Returns

#Set the spend limit

#Parameters

#Returns

#Get current spend

#Parameters

#Returns

The App object

Attributes

Create an app

Parameters

Returns

Retrieve an app

Parameters

Returns

Update an app

Parameters

Returns

List apps

Parameters

Returns

Archive an app

Parameters

Returns

Enable hosting

Parameters

Returns

Update hosting configuration

Parameters

Returns

Update player configuration

Parameters

Returns

Set the spend limit

Parameters

Returns

Get current spend

Parameters

Returns