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.
Read time 2 minutesLast updated 14 days ago
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 or
these advanced examples on GitHub.
The command runs a simple, standalone HTTP server that listens for your API requests.
cm apiWarning
The user account that runs the command needs a valid Unity
Version Control client configuration. To check your setup, run from your terminal.
cm apicm checkconnectionNote
You'll find the application in your Unity Version Control client directory:
cm- 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 command in your shell.
cm apiNote
To see all the options for the command, run .
cm apicm api --helpRefer to the following syntax for the command:
cm apicm api [(-p | --port) <portnumber>] [-r | --remote]
The following parameters are available:
- : Sets the port number for the API server. If you don't specify one, the default is
-p | --port <portnumber>.9090 - : Allows the server to accept remote connections from other hosts, not just the local machine.
-r | --remote
Examples
To start the API on the default port () and accept only local connections:
9090cm api
To start the API on port and accept only local connections:
65000cm api -p 65000
To start the API on the default port () and accept remote connections:
9090cm api -r
To start the API on port and accept remote connections:
65000cm api -p 65000 -r
When the API server starts successfully, you'll receive the following message:
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:
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 doesn't start is an unconfigured Unity Version Control user.
cm apiThe user account running needs a valid client configuration for a Unity Version Control server (Cloud or
on-premises). To check your configuration, run in a terminal with the same user account.
cm apicm checkconnectionIf the command returns the following message, your configuration is valid:
Test connection executed successfully
If you get a different message, follow the instructions in the output to fix your configuration.