How to use the Unity Version Control client REST API

Loading...

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.

If you're looking for a starting point, refer to our API client examples or these advanced examples on GitHub.

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

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.

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.

To see all the options for the cm api command, run cm api --help.

Refer to the following syntax for the cm api command:

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:

cm api

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

cm api -p 65000

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

cm api -r

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

cm 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 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:

Test connection executed successfully

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