Skip to content

Files & Public Links API

Manage build files and create shareable public links for distribution.

File Endpoints

List Build Files

GET /api/v1/workspace/{workspaceSlug}/project/{projectSlug}/build/{buildId}/file

List all files attached to a build.

Path Parameters

Parameter Type Description
workspaceSlug string Workspace identifier
projectSlug string Project identifier
buildId string Build identifier

Response

[
  {
    "fileId": "file123xyz",
    "name": "app.ipa",
    "size": 52428800,
    "path": "app.ipa",
    "fileExtension": "ipa",
    "createdAt": "2024-02-15T10:35:00Z"
  },
  {
    "fileId": "file456abc",
    "name": "app.dSYM.zip",
    "size": 15728640,
    "path": "app.dSYM.zip",
    "fileExtension": "zip",
    "createdAt": "2024-02-15T10:36:00Z"
  }
]

Required Permission: PROJECT_READ

Get Build Files (Alternative)

GET /api/v1/workspace/{workspaceSlug}/project/{projectSlug}/build/{buildId}/files

Alternative endpoint with additional file details.

Response

[
  {
    "fileId": "file123xyz",
    "name": "app.ipa",
    "size": 52428800,
    "extension": "ipa",
    "createdAt": "2024-02-15T10:35:00Z"
  }
]

Get File Download URL

GET /api/v1/workspace/{workspaceSlug}/project/{projectSlug}/build/file/{fileId}

Get a signed URL to download a file.

Path Parameters

Parameter Type Description
workspaceSlug string Workspace identifier
projectSlug string Project identifier
fileId string File identifier

Response

Returns the signed URL as a plain string:

"https://s3.example.com/bucket/workspace/project/build/file.ipa?X-Amz-Signature=..."

Required Permission: BUILD_DOWNLOAD

Delete File

DELETE /api/v1/workspace/{workspaceSlug}/project/{projectSlug}/build/file/{fileId}

Delete a file from a build.

Path Parameters

Parameter Type Description
workspaceSlug string Workspace identifier
projectSlug string Project identifier
fileId string File identifier

Required Permission: BUILD_DELETE

Storage Update

Deleting a file will decrease the workspace's storage usage accordingly.

Public links allow sharing files without authentication.

POST /api/v1/workspace/{workspaceSlug}/project/{projectSlug}/build/files/{fileId}/public-link

Create a shareable public link for a file.

Path Parameters

Parameter Type Description
workspaceSlug string Workspace identifier
projectSlug string Project identifier
fileId string File identifier

Request Body

{
  "downloadLimit": 100,
  "expirationDate": "2024-03-15T00:00:00Z",
  "isPermanent": false
}
Field Type Required Description
downloadLimit integer No Maximum number of downloads
expirationDate string No ISO 8601 expiration date
isPermanent boolean No If true, link never expires

Response

{
  "publicLinkId": "link123xyz",
  "fileId": "file123xyz",
  "expirationDate": "2024-03-15T00:00:00Z",
  "downloadLimit": 100,
  "accessCount": 0,
  "publicUrl": "https://api.usetotis.com/api/v1/public/file/link123xyz/app.ipa",
  "isActive": true,
  "isPermanent": false
}

Required Permission: BUILD_CREATE_LINKS

GET /api/v1/workspace/{workspaceSlug}/project/{projectSlug}/build/{buildId}/public-links

List all public links for a build's files.

Response

[
  {
    "publicLinkId": "link123xyz",
    "fileId": "file123xyz",
    "expirationDate": "2024-03-15T00:00:00Z",
    "downloadLimit": 100,
    "accessCount": 42,
    "publicUrl": "https://api.usetotis.com/api/v1/public/file/link123xyz/app.ipa",
    "isActive": true,
    "isPermanent": false
  }
]

Required Permission: BUILD_DOWNLOAD

DELETE /api/v1/workspace/{workspaceSlug}/project/{projectSlug}/build/files/{fileId}/public-links/{publicLinkId}

Deactivate a public link.

Path Parameters

Parameter Type Description
workspaceSlug string Workspace identifier
projectSlug string Project identifier
fileId string File identifier
publicLinkId string Public link identifier

Required Permission: BUILD_DELETE

Public Access Endpoints

These endpoints are accessible without authentication.

GET /api/v1/public/file/{publicLinkId}/{fileName}

Download a file using a public link. Redirects to the signed S3 URL.

Path Parameters

Parameter Type Description
publicLinkId string Public link identifier
fileName string File name

Response

HTTP 302 redirect to the signed download URL.

Error Responses

Status Error Description
404 LINK_NOT_FOUND Link doesn't exist or is inactive
403 DOWNLOAD_LIMIT_REACHED Maximum downloads exceeded

Get QR Code

GET /api/v1/public/file/{publicLinkId}/qr

Generate a QR code for a public link.

Path Parameters

Parameter Type Description
publicLinkId string Public link identifier

Response

Returns a PNG image (200x200 pixels) containing the QR code.

Response Headers

Content-Type: image/png

# Create a public link with 100 downloads, expiring in 7 days
EXPIRATION=$(date -v+7d +%Y-%m-%dT00:00:00Z)

curl -X POST \
  "https://api.usetotis.com/api/v1/workspace/my-company/project/ios-app/build/files/file123/public-link" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"downloadLimit\": 100,
    \"expirationDate\": \"$EXPIRATION\",
    \"isPermanent\": false
  }"

Response:

{
  "publicLinkId": "link789abc",
  "publicUrl": "https://api.usetotis.com/api/v1/public/file/link789abc/app.ipa"
}

Share the publicUrl with your testers. They can download directly without authentication.

Access Tracking

Public link access is logged with:

  • Timestamp
  • Client IP address
  • User agent (when available)

Access logs are stored in the PublicLinkAccessLog table and can be used for analytics.