The Origin object

Origins are storage locations for video inputs and transcoded outputs. Transcodely supports Google Cloud Storage, Amazon S3, and HTTP/HTTPS endpoints. Credentials are validated at creation and stored encrypted.

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

Attributes

Attribute	Type	Description
`id`	string	Unique identifier with `ori_` prefix (e.g., `"ori_x9y8z7w6v5"`).
`name`	string	Human-readable name.
`description`	string	Optional description.
`provider`	string	Storage provider. One of `"gcs"`, `"s3"`, `"http"`.
`permissions`	string[]	Declared permissions: `"read"` and/or `"write"`.
`status`	string	Current status. One of `"active"`, `"failed"`, `"archived"`.
`base_path`	string	Base path prefix within the bucket (e.g., `"videos/uploads/"`).
`path_template`	string	Output path template with variables (e.g., `"{date}/{job_id}/{codec}_{resolution}"`). Supports `{date}`, `{job_id}`, `{output_id}`, `{codec}`, `{resolution}`.
`last_validated_at`	string	ISO 8601 timestamp of last successful validation. Omitted if never validated.
`validation_error`	string	Error from last failed validation. Omitted if status is not `"failed"`.
`created_at`	string	ISO 8601 timestamp.
`updated_at`	string	ISO 8601 timestamp.
`archived_at`	string	ISO 8601 timestamp. Omitted if not archived.

{
  "id": "ori_x9y8z7w6v5",
  "name": "Production GCS Bucket",
  "description": "Main storage for video assets",
  "provider": "gcs",
  "permissions": ["read", "write"],
  "status": "active",
  "base_path": "videos/",
  "path_template": "{date}/{job_id}/{codec}_{resolution}",
  "last_validated_at": "2025-01-15T10:30:00Z",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Providers

Provider	Read	Write	Authentication
`gcs`	Yes	Yes	Service account JSON key.
`s3`	Yes	Yes	Access key ID and secret.
`http`	Yes	No	Optional custom headers.

The ValidationResult object

Returned when credentials are validated, either at creation, after credential rotation, or via the Validate endpoint.

Attribute	Type	Description
`success`	boolean	Whether all declared permissions were validated.
`can_read`	boolean	Whether read permission was validated.
`can_write`	boolean	Whether write permission was validated.
`read_error`	string	Error message if read validation failed.
`write_error`	string	Error message if write validation failed.
`validated_at`	string	ISO 8601 timestamp.

Create an origin

Create a new storage origin. Credentials are validated at creation time and must pass before the origin is stored.

POST /transcodely.v1.OriginService/Create

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Human-readable name (1-255 chars).
`description`	string	No	Description (max 1000 chars).
`permissions`	string[]	Yes	Declared permissions: `"read"` and/or `"write"`. At least one required. HTTP origins only support `"read"`.
`base_path`	string	No	Base path prefix within the bucket (max 1024 chars).
`path_template`	string	No	Output path template with variables like `{date}`, `{job_id}`, `{output_id}`, `{codec}`, `{resolution}` (max 1024 chars).
`gcs`	object	One of	GCS provider configuration. Exactly one of `gcs`, `s3`, or `http` must be provided.
`gcs.bucket`	string	Yes	GCS bucket name (e.g., `"my-video-bucket"`).
`gcs.credentials`	object	Yes	GCS credentials.
`gcs.credentials.service_account_json`	string	Yes	Full JSON content of the service account key file.
`s3`	object	One of	S3 provider configuration.
`s3.bucket`	string	Yes	S3 bucket name.
`s3.region`	string	Yes	AWS region (e.g., `"us-east-1"`).
`s3.credentials`	object	Yes	S3 credentials.
`s3.credentials.access_key_id`	string	Yes	AWS access key ID.
`s3.credentials.secret_access_key`	string	Yes	AWS secret access key.
`http`	object	One of	HTTP provider configuration (read-only).
`http.base_url`	string	Yes	Base URL (e.g., `"https://cdn.example.com/videos/"`).
`http.credentials`	object	No	Optional authentication headers.
`http.credentials.headers`	object	No	Key-value map of custom headers (max 20 pairs).

Returns

The Origin object and a ValidationResult confirming the credential check.

Example: GCS origin

curl -X POST https://api.transcodely.com/transcodely.v1.OriginService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Production GCS Bucket",
    "description": "Main storage for video assets",
    "permissions": ["read", "write"],
    "base_path": "videos/",
    "path_template": "{date}/{job_id}/{codec}_{resolution}",
    "gcs": {
      "bucket": "acme-video-assets",
      "credentials": {
        "service_account_json": "{...}"
      }
    }
  }'

{
  "origin": {
    "id": "ori_x9y8z7w6v5",
    "name": "Production GCS Bucket",
    "description": "Main storage for video assets",
    "provider": "gcs",
    "permissions": ["read", "write"],
    "status": "active",
    "base_path": "videos/",
    "path_template": "{date}/{job_id}/{codec}_{resolution}",
    "last_validated_at": "2025-01-15T10:30:00Z",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  },
  "validation": {
    "success": true,
    "can_read": true,
    "can_write": true,
    "read_error": "",
    "write_error": "",
    "validated_at": "2025-01-15T10:30:00Z"
  }
}

Example: S3 origin

curl -X POST https://api.transcodely.com/transcodely.v1.OriginService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "AWS S3 Output Bucket",
    "permissions": ["write"],
    "s3": {
      "bucket": "acme-transcoded-output",
      "region": "us-east-1",
      "credentials": {
        "access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
      }
    }
  }'

Retrieve an origin

Retrieve an origin by ID. Credentials are never included in responses.

POST /transcodely.v1.OriginService/Get

Parameters

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

Returns

The Origin object.

Example

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

{
  "origin": {
    "id": "ori_x9y8z7w6v5",
    "name": "Production GCS Bucket",
    "description": "Main storage for video assets",
    "provider": "gcs",
    "permissions": ["read", "write"],
    "status": "active",
    "base_path": "videos/",
    "path_template": "{date}/{job_id}/{codec}_{resolution}",
    "last_validated_at": "2025-01-15T10:30:00Z",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

List origins

List origins with optional filtering by provider, status, and permission.

POST /transcodely.v1.OriginService/List

Parameters

Parameter	Type	Required	Description
`provider`	string	No	Filter by provider: `"gcs"`, `"s3"`, or `"http"`.
`status`	string	No	Filter by status: `"active"`, `"failed"`, or `"archived"`.
`permission`	string	No	Filter by permission: `"read"` or `"write"`.
`include_archived`	boolean	No	Include archived origins. Default: `false`.
`pagination`	object	No	Pagination parameters. See Pagination.

Returns

A list of Origin objects and pagination metadata.

Example

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

{
  "origins": [
    {
      "id": "ori_x9y8z7w6v5",
      "name": "Production GCS Bucket",
      "provider": "gcs",
      "permissions": ["read", "write"],
      "status": "active",
      "base_path": "videos/",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "",
    "total_count": 1
  }
}

Update an origin

Update an origin’s metadata and optionally rotate credentials. If credentials are provided, validation runs automatically.

POST /transcodely.v1.OriginService/Update

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Origin ID.
`name`	string	No	New name (1-255 chars).
`description`	string	No	New description (max 1000 chars).
`base_path`	string	No	New base path (max 1024 chars).
`path_template`	string	No	New path template (max 1024 chars).
`gcs_credentials`	object	No	Updated GCS credentials. Triggers validation.
`s3_credentials`	object	No	Updated S3 credentials. Triggers validation.
`http_credentials`	object	No	Updated HTTP credentials. Triggers validation.

Returns

The updated Origin object. Includes a ValidationResult if credentials were rotated.

Example

curl -X POST https://api.transcodely.com/transcodely.v1.OriginService/Update 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{
    "id": "ori_x9y8z7w6v5",
    "name": "Production GCS (Updated)",
    "path_template": "{job_id}/{output_id}"
  }'

{
  "origin": {
    "id": "ori_x9y8z7w6v5",
    "name": "Production GCS (Updated)",
    "description": "Main storage for video assets",
    "provider": "gcs",
    "permissions": ["read", "write"],
    "status": "active",
    "base_path": "videos/",
    "path_template": "{job_id}/{output_id}",
    "last_validated_at": "2025-01-15T10:30:00Z",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-02-28T15:00:00Z"
  }
}

Validate an origin

Re-validate an origin’s credentials and permissions. Use this to check for permission drift after IAM policy changes.

POST /transcodely.v1.OriginService/Validate

Parameters

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

Returns

The Origin object (status may change to "active" or "failed") and a ValidationResult.

Example

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

{
  "origin": {
    "id": "ori_x9y8z7w6v5",
    "name": "Production GCS Bucket",
    "provider": "gcs",
    "permissions": ["read", "write"],
    "status": "active",
    "last_validated_at": "2025-02-28T15:00:00Z",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-02-28T15:00:00Z"
  },
  "validation": {
    "success": true,
    "can_read": true,
    "can_write": true,
    "read_error": "",
    "write_error": "",
    "validated_at": "2025-02-28T15:00:00Z"
  }
}

Archive an origin

Soft-delete an origin. Archived origins cannot be used for new jobs, but existing job data is preserved.

POST /transcodely.v1.OriginService/Archive

Parameters

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

Returns

The archived Origin object with status: "archived".

Example

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

{
  "origin": {
    "id": "ori_x9y8z7w6v5",
    "name": "Production GCS Bucket",
    "provider": "gcs",
    "permissions": ["read", "write"],
    "status": "archived",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-02-28T15:00:00Z",
    "archived_at": "2025-02-28T15:00:00Z"
  }
}

#The Origin object

#Attributes

#Providers

#The ValidationResult object

#Create an origin

#Parameters

#Returns

#Example: GCS origin

#Example: S3 origin

#Retrieve an origin

#Parameters

#Returns

#Example

#List origins

#Parameters

#Returns

#Example

#Update an origin

#Parameters

#Returns

#Example

#Validate an origin

#Parameters

#Returns

#Example

#Archive an origin

#Parameters

#Returns

#Example

The Origin object

Attributes

Providers

The ValidationResult object

Create an origin

Parameters

Returns

Example: GCS origin

Example: S3 origin

Retrieve an origin

Parameters

Returns

Example

List origins

Parameters

Returns

Example

Update an origin

Parameters

Returns

Example

Validate an origin

Parameters

Returns

Example

Archive an origin

Parameters

Returns

Example