Storage connections

Save AWS S3 credentials on a project so jobs can read source media and write outputs through a storage connection. Manage connections from the dashboard or programmatically with a project API key (with storage_connection:* permissions) or user session.

After creating a connection, submit transcription jobs with input.sourceType: s3_direct and the connection's connectionId. See Create a transcription job.

Automatic connection tests — the API probes S3 credentials and bucket permissions on POST (create), on PATCH when credentials, region, buckets, or status: active (reactivation) change, and on the dedicated …/test endpoint. Failed probes return 422 validationError and the connection is not saved (create) or not updated (patch). Use …/probe or …/test-credentials to validate interactively before submit.

Endpoints

The Storage connection object

connectionIdstring
Stable connection identifier (UUID).
namestring
Human-readable label (1–64 characters).
providerstring
Currently s3 only.
regionstring
AWS region (e.g. us-east-1).
accessKeyIdstring
IAM access key id used for S3 calls.
secretAccessKeySetboolean
True when a secret access key is stored. The secret is never returned after create.
bucketsobject[]
Allowed buckets (at least one). Each entry has name and optional defaultOutputPrefix — Root folder for versioned s3_direct job outputs when input.outputPrefix is omitted. Resolved paths follow {defaultOutputPrefix}/{transcriptionId}/{transcripts|clips|thumbnails}/. Defaults to perchat-media-results when unset on the bucket. See Create a transcription job.
buckets[].namestring
S3 bucket name.
buckets[].defaultOutputPrefixstring, optional
Root folder for versioned s3_direct job outputs when input.outputPrefix is omitted. Resolved paths follow {defaultOutputPrefix}/{transcriptionId}/{transcripts|clips|thumbnails}/. Defaults to perchat-media-results when unset on the bucket.
statusstring
active or inactive. Inactive connections are hidden from job create and rejected by s3_direct validation.
lastTestedAttimestamp | null, optional
When the connection was last tested.
lastTestStatusstring | null, optional
ok or failed from the most recent test; null if never tested.
createdAttimestamp
Creation time.
updatedAttimestamp
Last update time.
createdBystring
User id or api_key actor that created the connection.
updatedBystring
User id or api_key actor that last updated the connection.
createdByUsernamestring, optional
Resolved username for createdBy (api_key or system when applicable).
updatedByUsernamestring, optional
Resolved username for updatedBy.

Create a storage connection

POST/v1/storage-connections
Stores encrypted S3 credentials for a project. The API runs a full bucket permission test before saving; the returned object includes lastTestStatus: ok when probes succeed.

When to use

  • Reusable S3 access — one connection for transcription, clips, and thumbnail jobs.
  • Automation — provision connections from CI with a project API key that has storage_connection:create.

Requires permission

storage_connection:create

Authenticate with a project API key (sk_prj_…) with the matching storage_connection:* permission — the project is bound to the key automatically — or with a dashboard user session (Authorization: Bearer <jwt>) plus X-Workspace-Id and X-Project-Id headers (same as jobs and transcriptions). Workspace API keys (sk_wsp_…) cannot access these routes — use them to create projects and mint project keys instead.

Automatic connection tests — the API probes S3 credentials and bucket permissions on POST (create), on PATCH when credentials, region, buckets, or status: active (reactivation) change, and on the dedicated …/test endpoint. Failed probes return 422 validationError and the connection is not saved (create) or not updated (patch). Use …/probe or …/test-credentials to validate interactively before submit.

Example body:
{
  "name": "Primary S3",
  "provider": "s3",
  "region": "us-east-1",
  "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
  "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "buckets": [
    {
      "name": "my-bucket",
      "defaultOutputPrefix": "perchat-media-results"
    },
    {
      "name": "my-backup-bucket",
      "defaultOutputPrefix": ""
    }
  ]
}
Duplicate connection names or duplicate access-key + secret pairs within a project return 409 conflict.

Parameters

namestring
Connection label (1–64 characters).
providerstring
Must be s3.
regionstring
AWS region for the S3 client.
accessKeyIdstring
IAM access key id.
secretAccessKeystring
IAM secret access key. Stored encrypted; shown only in this request.
bucketsobject[]
One or more bucket configs (name + optional defaultOutputPrefix).
buckets[].namestring
S3 bucket name.
buckets[].defaultOutputPrefixstring, optional
Root folder for versioned s3_direct job outputs when input.outputPrefix is omitted. Resolved paths follow {defaultOutputPrefix}/{transcriptionId}/{transcripts|clips|thumbnails}/. Defaults to perchat-media-results when unset on the bucket.

Returns

Returns the created Storage connection (HTTP 201) with test metadata populated.

See the the storage connection object for attribute details.

List storage connections

GET/v1/storage-connections
Lists storage connections for the project.

Requires permission

storage_connection:list

Authenticate with a project API key (sk_prj_…) with the matching storage_connection:* permission — the project is bound to the key automatically — or with a dashboard user session (Authorization: Bearer <jwt>) plus X-Workspace-Id and X-Project-Id headers (same as jobs and transcriptions). Workspace API keys (sk_wsp_…) cannot access these routes — use them to create projects and mint project keys instead.

Parameters

activeOnlyquery, optional
When 1, true, or yes, returns only status: active connections (used by job create UIs).

Retrieve a storage connection

GET/v1/storage-connections/{connectionId}
Returns one storage connection by id.

Requires permission

storage_connection:read

Authenticate with a project API key (sk_prj_…) with the matching storage_connection:* permission — the project is bound to the key automatically — or with a dashboard user session (Authorization: Bearer <jwt>) plus X-Workspace-Id and X-Project-Id headers (same as jobs and transcriptions). Workspace API keys (sk_wsp_…) cannot access these routes — use them to create projects and mint project keys instead.

Update a storage connection

PATCH/v1/storage-connections/{connectionId}
Partial update for name, credentials, buckets, or status. Changing credentials, region, buckets, or reactivating (status: active from inactive) triggers an automatic connection test; the update is rejected if probes fail.

Requires permission

storage_connection:update

Authenticate with a project API key (sk_prj_…) with the matching storage_connection:* permission — the project is bound to the key automatically — or with a dashboard user session (Authorization: Bearer <jwt>) plus X-Workspace-Id and X-Project-Id headers (same as jobs and transcriptions). Workspace API keys (sk_wsp_…) cannot access these routes — use them to create projects and mint project keys instead.

Example body (buckets only):
{
  "buckets": [
    {
      "name": "my-bucket",
      "defaultOutputPrefix": "perchat-media-results"
    },
    {
      "name": "my-backup-bucket",
      "defaultOutputPrefix": ""
    },
    {
      "name": "archive-bucket",
      "defaultOutputPrefix": "customer-archive"
    }
  ]
}

Parameters

namestring, optional
Updated label.
regionstring, optional
Updated AWS region.
accessKeyIdstring, optional
Updated access key id.
secretAccessKeystring, optional
New secret (omit to keep the stored secret).
bucketsobject[], optional
Replaces the allowed bucket list (same shape as create).
statusstring, optional
active or inactive. Deactivating does not run a test; reactivating does.

Returns

Returns the updated Storage connection.

See the the storage connection object for attribute details.

Delete a storage connection

DELETE/v1/storage-connections/{connectionId}
Permanently removes a storage connection. Existing jobs that referenced it are unchanged.

Requires permission

storage_connection:delete

Authenticate with a project API key (sk_prj_…) with the matching storage_connection:* permission — the project is bound to the key automatically — or with a dashboard user session (Authorization: Bearer <jwt>) plus X-Workspace-Id and X-Project-Id headers (same as jobs and transcriptions). Workspace API keys (sk_wsp_…) cannot access these routes — use them to create projects and mint project keys instead.

Test a storage connection

POST/v1/storage-connections/{connectionId}/test
Re-runs the stored credential and bucket permission probes for an existing connection. Updates lastTestedAt and lastTestStatus on the connection record. Does not change credentials or buckets — use this for health checks (the dashboard runs this for all active connections on page load).

Requires permission

storage_connection:update

Authenticate with a project API key (sk_prj_…) with the matching storage_connection:* permission — the project is bound to the key automatically — or with a dashboard user session (Authorization: Bearer <jwt>) plus X-Workspace-Id and X-Project-Id headers (same as jobs and transcriptions). Workspace API keys (sk_wsp_…) cannot access these routes — use them to create projects and mint project keys instead.

Returns

Returns test (probe details) and the updated connection object.

See the the storage connection object for attribute details.

Probe credentials and buckets (pre-save)

POST/v1/storage-connections/probe
Tests credentials and bucket permissions without saving a connection. Use while building a create/update form. Same probe logic as create/patch enforcement and …/test.

Requires permission

storage_connection:update

Authenticate with a project API key (sk_prj_…) with the matching storage_connection:* permission — the project is bound to the key automatically — or with a dashboard user session (Authorization: Bearer <jwt>) plus X-Workspace-Id and X-Project-Id headers (same as jobs and transcriptions). Workspace API keys (sk_wsp_…) cannot access these routes — use them to create projects and mint project keys instead.

Example body:
{
  "region": "us-east-1",
  "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
  "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "buckets": [
    {
      "name": "my-bucket",
      "defaultOutputPrefix": ""
    }
  ]
}

Parameters

regionstring
AWS region.
accessKeyIdstring
IAM access key id.
secretAccessKeystring, optional
Secret key. Omit when connectionId is set to reuse the stored secret on an existing connection.
connectionIdstring, optional
Existing connection id (edit flows without re-entering the secret).
bucketsobject[]
Bucket configs to validate (name + optional defaultOutputPrefix).

Test AWS credentials only

POST/v1/storage-connections/test-credentials
Verifies that an access key and secret are valid (STS GetCallerIdentity) before bucket selection. Does not write to the connection record.

Requires permission

storage_connection:update

Authenticate with a project API key (sk_prj_…) with the matching storage_connection:* permission — the project is bound to the key automatically — or with a dashboard user session (Authorization: Bearer <jwt>) plus X-Workspace-Id and X-Project-Id headers (same as jobs and transcriptions). Workspace API keys (sk_wsp_…) cannot access these routes — use them to create projects and mint project keys instead.

Parameters

regionstring
AWS region.
accessKeyIdstring
IAM access key id.
secretAccessKeystring, optional
Secret key, or omit with connectionId to use stored secret.
connectionIdstring, optional
Existing connection id.

Discover accessible buckets

POST/v1/storage-connections/discover-buckets
Lists bucket names visible to the IAM principal (s3:ListAllMyBuckets). Optional helper when configuring a connection; not required for create.

Requires permission

storage_connection:update

Authenticate with a project API key (sk_prj_…) with the matching storage_connection:* permission — the project is bound to the key automatically — or with a dashboard user session (Authorization: Bearer <jwt>) plus X-Workspace-Id and X-Project-Id headers (same as jobs and transcriptions). Workspace API keys (sk_wsp_…) cannot access these routes — use them to create projects and mint project keys instead.

Storage connection job usage

GET/v1/storage-connections/{connectionId}/job-usage
Returns counts of s3_direct jobs that reference this connection (for delete / deactivate impact warnings).

Requires permission

storage_connection:read

Authenticate with a project API key (sk_prj_…) with the matching storage_connection:* permission — the project is bound to the key automatically — or with a dashboard user session (Authorization: Bearer <jwt>) plus X-Workspace-Id and X-Project-Id headers (same as jobs and transcriptions). Workspace API keys (sk_wsp_…) cannot access these routes — use them to create projects and mint project keys instead.

Browse bucket objects

GET/v1/storage-connections/{connectionId}/buckets/{bucket}/objects
Lists folders and objects under an optional prefix in a bucket allowed on the connection. Supports cursor pagination via cursor. Callers with job:create (without storage_connection:read) may also browse when picking objects for S3 direct jobs.

Requires permission

storage_connection:read

Authenticate with a project API key (sk_prj_…) with the matching storage_connection:* permission — the project is bound to the key automatically — or with a dashboard user session (Authorization: Bearer <jwt>) plus X-Workspace-Id and X-Project-Id headers (same as jobs and transcriptions). Workspace API keys (sk_wsp_…) cannot access these routes — use them to create projects and mint project keys instead.

Parameters

prefixstring, optional
Object key prefix filter.
cursorstring, optional
Pagination token from a previous response.