# How to use the Unity Version Control client REST API

> Learn how to start the Unity Version Control client REST API with the cm api command and troubleshoot the API server.

The Unity Version Control Client REST API supports command execution through standard HTTP requests. Use any programming language capable of making HTTP calls to interact with the API. Make sure you use the right HTTP method and include the request body that the endpoint expects.

> **Note:**
>
> If you're looking for a starting point, refer to our [API client examples](/services-web-apis/unity-version-control-cm/examples.md) or
> these [advanced examples on GitHub](https://github.com/PlasticSCM/api-rest-examples).

The `cm api` command runs a simple, standalone HTTP server that listens for your API requests.

> **Warning:**
>
> The user account that runs the `cm api` command needs a valid Unity
> Version Control client configuration. To check your setup, run `cm checkconnection` from your terminal.

> **Note:**
>
> You'll find the `cm` application in your Unity Version Control client directory:
>
> * Windows: `C:\Program Files\PlasticSCM5\client`
> * macOS: `/Applications/PlasticSCM.app/Contents/Applications`
> * Linux: `/opt/plasticscm5/client`

## Start the API

To start the client API HTTP server, run the `cm api` command in your shell.

> **Note:**
>
> To see all the options for the `cm api` command, run `cm api --help`.

Refer to the following syntax for the `cm api` command:

```text
cm api [(-p | --port) <portnumber>] [-r | --remote]
```

The following parameters are available:

* `-p | --port <portnumber>`: Sets the port number for the API server. If you don't specify one, the default is `9090`.
* `-r | --remote`: Allows the server to accept remote connections from other hosts, not just the local machine.

### Examples

To start the API on the default port (`9090`) and accept only local connections:

```bash
cm api
```

To start the API on port `65000` and accept only local connections:

```bash
cm api -p 65000
```

To start the API on the default port (`9090`) and accept remote connections:

```bash
cm api -r
```

To start the API on port `65000` and accept remote connections:

```bash
cm api -p 65000 -r
```

When the API server starts successfully, you'll receive the following message:

```text
Unity VCS client REST API: Press <ENTER> to exit.
```

## Troubleshooting

### If the API server does not start

If the API fails to start, you'll receive a message like the following:

```text
Unable to start the REST API listener. Please make sure that you have HTTP permissions for the current port and user.
```

The most common reason `cm api` doesn't start is an unconfigured Unity Version Control user.

The user account running `cm api` needs a valid client configuration for a Unity Version Control server (Cloud or
on-premises). To check your configuration, run `cm checkconnection` in a terminal with the same user account.

If the command returns the following message, your configuration is valid:

```text
Test connection executed successfully
```

If you get a different message, follow the instructions in the output to fix your configuration.