The App object

Apps are projects within an organization. Each app has its own API keys, jobs, origins, presets, and webhook configuration. 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.
`webhook`	object \| null	Webhook configuration, or `null` if not configured.
`webhook.url`	string	Webhook endpoint URL.
`webhook.secret_hint`	string	Last 4 characters of the signing secret. Omitted if no secret.
`webhook.has_secret`	boolean	Whether a signing secret is configured.
`webhook.events`	string[]	Subscribed event types.
`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.

{
  "id": "app_k1l2m3n4o5",
  "org_id": "org_f6g7h8i9j0",
  "name": "Production",
  "description": "Production video processing",
  "webhook": {
    "url": "https://api.example.com/webhooks/transcodely",
    "secret_hint": "x7w9",
    "has_secret": true,
    "events": ["job.completed", "job.failed", "job.progress"]
  },
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Webhook events

job.completed, job.failed, job.progress, job.canceled, output.completed, output.failed

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).
`webhook`	object	No	Webhook configuration.
`webhook.url`	string	Yes*	HTTPS endpoint URL for receiving webhooks. *Required if `webhook` is provided.
`webhook.generate_secret`	boolean	No	If `true`, a webhook signing secret is generated and returned.
`webhook.events`	string[]	No	Events to subscribe to. Default: `["job.completed", "job.failed"]`.

Returns

Returns an App object.

When generate_secret is true, the response also includes a webhook_secret field. Store this securely — it is shown only once.

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",
    "webhook": {
      "url": "https://api.example.com/webhooks/transcodely",
      "generate_secret": true,
      "events": ["job.completed", "job.failed", "job.progress"]
    }
  }'

{
  "app": {
    "id": "app_k1l2m3n4o5",
    "org_id": "org_f6g7h8i9j0",
    "name": "Production",
    "description": "Production video processing",
    "webhook": {
      "url": "https://api.example.com/webhooks/transcodely",
      "secret_hint": "x7w9",
      "has_secret": true,
      "events": ["job.completed", "job.failed", "job.progress"]
    },
    "status": "active",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  },
  "webhook_secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

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"}'

{
  "app": {
    "id": "app_k1l2m3n4o5",
    "org_id": "org_f6g7h8i9j0",
    "name": "Production",
    "description": "Production video processing",
    "webhook": {
      "url": "https://api.example.com/webhooks/transcodely",
      "secret_hint": "x7w9",
      "has_secret": true,
      "events": ["job.completed", "job.failed", "job.progress"]
    },
    "status": "active",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Update an app

Update an app’s name, description, and webhook configuration.

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).
`webhook`	object	No	Updated webhook configuration.
`webhook.url`	string	No	New webhook URL. Set to empty string to disable webhooks.
`webhook.regenerate_secret`	boolean	No	If `true`, generate a new signing secret. The new secret is returned in the response.
`webhook.events`	string[]	No	New event subscriptions. Only applied if explicitly provided.

Returns

Returns the updated App object.

When regenerate_secret is true, the response also includes the new webhook_secret.

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)",
    "webhook": {
      "regenerate_secret": true
    }
  }'

{
  "app": {
    "id": "app_k1l2m3n4o5",
    "org_id": "org_f6g7h8i9j0",
    "name": "Production (v2)",
    "description": "Production video processing",
    "webhook": {
      "url": "https://api.example.com/webhooks/transcodely",
      "secret_hint": "p6q7",
      "has_secret": true,
      "events": ["job.completed", "job.failed", "job.progress"]
    },
    "status": "active",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-02-28T15:00:00Z"
  },
  "webhook_secret": "whsec_r7s8t9u0v1w2x3y4z5a6b7c8d9e0f1g2"
}

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}
  }'

{
  "apps": [
    {
      "id": "app_k1l2m3n4o5",
      "org_id": "org_f6g7h8i9j0",
      "name": "Production",
      "description": "Production video processing",
      "webhook": {
        "url": "https://api.example.com/webhooks/transcodely",
        "has_secret": true,
        "events": ["job.completed", "job.failed", "job.progress"]
      },
      "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"}'

{
  "app": {
    "id": "app_k1l2m3n4o5",
    "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"
  }
}

#The App object

#Attributes

#Webhook events

#Create an app

#Parameters

#Returns

#Retrieve an app

#Parameters

#Returns

#Update an app

#Parameters

#Returns

#List apps

#Parameters

#Returns

#Archive an app

#Parameters

#Returns

The App object

Attributes

Webhook events

Create an app

Parameters

Returns

Retrieve an app

Parameters

Returns

Update an app

Parameters

Returns

List apps

Parameters

Returns

Archive an app

Parameters

Returns