# API

How to remotely interact with UBuild!

# Basic Usage

Welcome to the UBuild API, a remote interaction service within the UBuild tool. This API allows you to interact with the UBuild application via API endpoints.

The UBuild API can be configured to work locally (within a LAN) or can be port-forwarded to be accessed from the internet. For security, by default, you must use an API key defined within the api.config. *(see more about configuring the API [here](https://docs.publiczeus.com/books/getting-started-with-ubuild/page/api-configuration "API Configuration")) (this can be disabled if only using UBuild within a LAN)*

Included within each UBuild release is a [Postman](https://www.postman.com/) collection that you can import *(documentation/UBuild.postman\_collection.json)*, this collection will setup setup all UBuild endpoints within a UBuild Collection in Postman.

The UBuild API will automatically start when the application begins, so-long as the UBuild application is open- you will be able to use the API.

# Retrieving Information

Using the UBuild API you can retrieve information using the HTTP GET method.

## Methods

Below are the endpoints you can use to retrieve information from UBuild:

### /queue

Get all the currently queued builds.  
**Accepts:**

- Query/Params 
    - "token" - The user's access token. (optional; depending on api.config)

**Returns:**

- A JSON array of objects representing queued builds.

---

### /report

Gets a build reporting matching the UID provided.  
**Accepts:**

- Query/Params 
    - "token" - The user's access token. (optional; defined in api.config)
    - "uid" - The UID of the build for which you want to receive a report.

**Returns:**

- A JSON object representing the build report.

---

### /reports

Gets all currently stored build reports.  
**Accepts:**

- Query/Params 
    - "token" - The user's access token. (optional; defined in api.config)

**Returns:**

- A JSON array of objects representing build reports.

# Sending Information

You can send information to the UBuild API to add builds to the queue, cancel builds and if needed; you can even shut down UBuild.

## Methods

Below are the endpoints you can use to retrieve information from UBuild:

### /queue/add

Add a build to the queue.  
**Accepts:**

- Query/Params 
    - "token" - The user's access token. (optional; depending on api.config)
- Body 
    - Basic Example:  
        ```json
        {
            "ProjectFilename": "Scary Stories (git)",
            "PresetName": "Steam",
            "PlatformName": "Windows"
        }
        ```
    - Advanced Example: *(with Preset overrides)* ```json
        {
            "ProjectFilename": "",
            "PresetName": "",
            "PlatformName": "",
            "ProjectOverrides": {
                "ProjectFolder": "",
                "GitUser": "",
                "GitToken": "",
                "GitBranch": "",
                "UnityFolder": ""
            },
            "PresetOverrides": {
                "MethodToExecute": "",
                "AdditionalBuildArgs": [],
                "BuildFolder": "",
                "IncludeFilesFromFolder": "",
                "ExcludeFilesFromBuild": [],
                "ExcludeFoldersFromBuild": [],
                "DeleteBuildExceptZip": false,
                "CompressToZip": false,
                "ForcePullFreshProject": false
            }
        }
        ```

**Returns:**

- A plain-text message with the result of the operation. (200 = success)

---

### /queue/cancel-current

This will cancel the currently in-progress build.

**Accepts:**

- Query/Params 
    - "token" - The user's access token. (optional; depending on api.config)

**Returns:**

- A plain-text message with the result of the operation. (200 = success)

---

### /queue/cancel-all

This will cancel all builds within the queue.

**Accepts:**

- Query/Params 
    - "token" - The user's access token. (optional; depending on api.config)

**Returns:**

- A plain-text message with the result of the operation. (200 = success)