Organization Files

The organization files API uploads files into organization-scoped storage and returns temporary access links for files stored under the organization.

Authenticate with a user API key or an organization service account token in the Authorization header. For user API keys, VoiceRun uses the caller's default organization unless you pass an Organization-Id or X-Org-Id header. Service account tokens are already bound to an organization.

These endpoints also require organization-level file permissions; users without the required role receive 403 Forbidden.

Base URL#

https://api.voicerun.com/v1/organization-files

Upload a File#

Upload a single file with multipart form data.

POST /v1/organization-files

Permissions#

Requires organization.file:create (admin tier).

Request#

Send the file in a multipart field named file.

curl -X POST https://api.voicerun.com/v1/organization-files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./voice-sample.wav"

Response#

{
  "url": "https://storage.example.com/..."
}

VoiceRun generates the stored filename and preserves the original file extension when one is present. Uploads must target the collection root (/v1/organization-files); do not append a filename or path to the upload URL.

Download or Resolve a File#

Resolve a file path stored under the organization.

GET /v1/organization-files/{filePath}

Permissions#

Requires organization.file:read (admin tier).

Behavior#

By default, the API redirects to a temporary signed URL for the file:

curl -L https://api.voicerun.com/v1/organization-files/path/to/file.wav \
  -H "Authorization: Bearer YOUR_API_KEY"

To receive the signed URL as JSON instead of following a redirect, add format=url:

curl "https://api.voicerun.com/v1/organization-files/path/to/file.wav?format=url" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "signedUrl": "https://storage.example.com/..."
}

Nested paths are supported in {filePath}.

Error Responses#