Projects API¶

Projects belong to workspaces and contain builds. Each project represents an application or component.

Endpoints¶

Create Project¶

PUT /api/v1/workspace/{workspaceSlug}/project

Create a new project within a workspace.

Path Parameters

Parameter	Type	Description
`workspaceSlug`	string	Workspace identifier

Request Body

{
  "name": "iOS App",
  "repository": "https://github.com/company/ios-app",
  "description": "Main iOS application",
  "image": "base64-encoded-image (optional)"
}

Field	Type	Required	Description
`name`	string	Yes	Project display name
`repository`	string	No	Repository URL
`description`	string	No	Project description
`image`	string	No	Base64-encoded project image

Response

{
  "projectId": "proj123xyz",
  "name": "iOS App",
  "projectSlug": "ios-app",
  "repository": "https://github.com/company/ios-app",
  "description": "Main iOS application",
  "imageUrl": null,
  "createdAt": "2024-01-15T10:30:00Z"
}

Required Permission: PROJECT_CREATE

Error Responses

Status	Error	Description
400	`SLUG_ALREADY_EXISTS`	Project slug already taken
400	`PROJECT_LIMIT_EXCEEDED`	Workspace reached max projects

Get Project¶

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

Retrieve project details with permissions.

Path Parameters

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

Response

{
  "workspace": {
    "workspaceId": "ws123",
    "name": "My Company",
    "slug": "my-company"
  },
  "project": {
    "projectId": "proj123xyz",
    "name": "iOS App",
    "projectSlug": "ios-app",
    "repository": "https://github.com/company/ios-app",
    "description": "Main iOS application",
    "imageUrl": "https://cdn.usetotis.com/images/proj123.png",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-02-01T14:20:00Z"
  },
  "permissions": [
    "PROJECT_READ",
    "PROJECT_EDIT",
    "BUILD_CREATE",
    "BUILD_UPLOAD"
  ]
}

Required Permission: PROJECT_READ

Update Project¶

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

Update project settings.

Path Parameters

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

Request Body

{
  "name": "iOS App v2",
  "repository": "https://github.com/company/ios-app-v2",
  "description": "Updated iOS application",
  "image": "base64-encoded-image (optional)",
  "removeImage": false
}

Field	Type	Required	Description
`name`	string	Yes	Updated display name
`repository`	string	No	Updated repository URL
`description`	string	No	Updated description
`image`	string	No	New base64-encoded image
`removeImage`	boolean	No	Set to `true` to remove the image

Required Permission: PROJECT_EDIT

Delete Project¶

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

Delete a project. The project must have no builds.

Path Parameters

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

Required Permission: PROJECT_DELETE

Cannot Be Undone

Project deletion is permanent. Ensure all builds are deleted first.

Error Responses

Status	Error	Description
400	`PROJECT_HAS_BUILDS`	Delete all builds first

Get Project Metrics¶

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

Get usage metrics for a project.

Path Parameters

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

Response

{
  "totalBuilds": 42,
  "totalStorageBytes": 1073741824,
  "latestBuild": {
    "buildId": "build123",
    "version": "1.5.0",
    "platform": "IOS",
    "buildType": "RELEASE",
    "createdAt": "2024-02-15T10:30:00Z"
  }
}

Field	Type	Description
`totalBuilds`	integer	Total number of builds
`totalStorageBytes`	integer	Total storage used in bytes
`latestBuild`	object	Most recent build (null if none)

Required Permission: PROJECT_READ

Project Slugs¶

Project slugs are automatically generated from the project name:

Converted to lowercase
Spaces replaced with hyphens
Special characters removed
Must be unique within the workspace

Examples:

Name	Slug
iOS App	`ios-app`
Android App v2	`android-app-v2`
My Awesome Project	`my-awesome-project`