Builds API¶

Builds represent versioned releases of your application. Each build can contain multiple files and metadata.

Endpoints¶

Search Builds¶

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

Search and list builds with optional filtering and pagination.

Path Parameters

Parameter	Type	Description
`workspaceSlug`	string	Workspace identifier
`projectSlug`	string	Project identifier

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (0-indexed)
`size`	integer	Page size (default: 20)
`sort`	string	Sort field and direction (e.g., `createdAt,desc`)
`searchTerm`	string	Search in version, commit hash, notes
`buildId`	string	Get specific build by ID
`platform`	string	Filter by platform: `IOS`, `ANDROID`, `WEB`, `DESKTOP`
`buildType`	string	Filter by type: `RELEASE`, `DEBUG`, `STAGING`, `NIGHTLY`

Response

[
  {
    "buildId": "build123xyz",
    "version": "1.5.0",
    "buildNumber": "150",
    "platform": "IOS",
    "buildType": "RELEASE",
    "commitHash": "abc123def456",
    "branchName": "main",
    "notes": "Bug fixes and performance improvements",
    "buildSize": 52428800,
    "createdAt": "2024-02-15T10:30:00Z"
  },
  {
    "buildId": "build456abc",
    "version": "1.4.0",
    "buildNumber": "140",
    "platform": "IOS",
    "buildType": "RELEASE",
    "commitHash": "def789ghi012",
    "branchName": "main",
    "notes": "New feature release",
    "buildSize": 48234567,
    "createdAt": "2024-02-01T14:20:00Z"
  }
]

Required Permission: PROJECT_READ

Create Build¶

POST /api/v1/workspace/{workspaceSlug}/project/{projectSlug}/build

Create a new build entry.

Request Body

{
  "version": "1.5.0",
  "buildNumber": "150",
  "platform": "IOS",
  "buildType": "RELEASE",
  "commitHash": "abc123def456",
  "branchName": "main",
  "notes": "Bug fixes and performance improvements"
}

Field	Type	Required	Description
`version`	string	Yes	Semantic version (e.g., "1.5.0")
`buildNumber`	string	No	Build number
`platform`	string	Yes	Target platform
`buildType`	string	Yes	Build type
`commitHash`	string	No	Git commit SHA
`branchName`	string	No	Git branch name
`notes`	string	No	Release notes

Platform Values

Value	Description
`IOS`	iOS application
`ANDROID`	Android application
`WEB`	Web application
`DESKTOP`	Desktop application

Build Type Values

Value	Description
`RELEASE`	Production release
`DEBUG`	Debug build
`STAGING`	Staging/QA build
`NIGHTLY`	Nightly build

Response

{
  "buildId": "build123xyz",
  "version": "1.5.0",
  "buildNumber": "150",
  "platform": "IOS",
  "buildType": "RELEASE",
  "commitHash": "abc123def456",
  "branchName": "main",
  "notes": "Bug fixes and performance improvements",
  "buildSize": 0,
  "createdAt": "2024-02-15T10:30:00Z"
}

Required Permission: BUILD_CREATE, BUILD_UPLOAD

Update Build¶

PUT /api/v1/workspace/{workspaceSlug}/project/{projectSlug}/build/{buildId}

Update build metadata.

Path Parameters

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

Request Body

{
  "version": "1.5.1",
  "buildNumber": "151",
  "platform": "IOS",
  "buildType": "RELEASE",
  "commitHash": "abc123def456",
  "branchName": "main",
  "notes": "Updated release notes"
}

Required Permission: BUILD_EDIT

Delete Build¶

DELETE /api/v1/workspace/{workspaceSlug}/project/{projectSlug}/build/{buildId}

Delete a build and all its associated files.

Path Parameters

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

Required Permission: BUILD_DELETE

Irreversible Action

Deleting a build permanently removes all associated files from storage.

Build Upload Workflow¶

Uploading files to a build is a three-step process:

Step 1: Get Signed Upload URL¶

POST /api/v1/workspace/{workspaceSlug}/project/{projectSlug}/build/{buildId}/sign

Get a pre-signed URL for uploading a file directly to S3.

Request Body

{
  "filename": "app.ipa"
}

Response

{
  "signedUrl": "https://s3.example.com/bucket/path?X-Amz-Signature=...",
  "signedToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Step 2: Upload File to S3¶

Upload your file directly to the signed URL:

curl -X PUT "SIGNED_URL" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@app.ipa"

Step 3: Confirm Upload¶

POST /api/v1/workspace/{workspaceSlug}/project/{projectSlug}/build/{buildId}/upload

Confirm the upload and register the file with the build.

Request Body

"SIGNED_TOKEN"

Token Format

Send the signed token as a plain JSON string (with quotes).

Response

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

Required Permission: BUILD_UPLOAD

Error Responses

Status	Error	Description
400	`STORAGE_LIMIT_EXCEEDED`	Workspace storage limit reached
404	`FILE_NOT_FOUND`	File not found at signed URL

Complete Upload Example¶

#!/bin/bash

WORKSPACE="my-company"
PROJECT="ios-app"
BUILD_ID="build123"
FILE="./app.ipa"

# Step 1: Get signed URL
RESPONSE=$(curl -s -X POST \
  "https://api.usetotis.com/api/v1/workspace/$WORKSPACE/project/$PROJECT/build/$BUILD_ID/sign" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"filename\": \"$(basename $FILE)\"}")

SIGNED_URL=$(echo $RESPONSE | jq -r '.signedUrl')
SIGNED_TOKEN=$(echo $RESPONSE | jq -r '.signedToken')

# Step 2: Upload to S3
curl -X PUT "$SIGNED_URL" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@$FILE"

# Step 3: Confirm upload
curl -X POST \
  "https://api.usetotis.com/api/v1/workspace/$WORKSPACE/project/$PROJECT/build/$BUILD_ID/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "\"$SIGNED_TOKEN\""

echo "Upload complete!"