Skip to main content

API Quickstart

Request your first workstation, use an AI browser operator, and release the workstation.

1. Get API key​

Aquire an API key by signing up, and creating a new API key on the API Keys page.

2. Request Workstation​

We will use the Request Workstation API endpoint to provision a new workstation.

  • $AGENTSTATION_API_KEY - Your bearer token, represented as a set environment variable in the examples below via export AGENTSTATION_API_KEY=<your_api_key>.
curl -X POST -L "https://api.agentstation.ai/v1/workstations" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AGENTSTATION_API_KEY" \
  -d '{}'

If successful, you will receive a response which will include a workstation id. You will need this id value to interact with the workstation. We will set an environment variable named $WORKSTATION_ID via export WORKSTATION_ID=<your_workstation_id> for the rest of the examples below.

{
  "id": "JfmNNOQ6O7VK",
  "name": "zen_shamir2",
  "type_id": "default",
  "status": "active",
  "tags": [],
  "launch_time": "219.977µs",
  "released_at": "0001-01-01T00:00:00Z",
  "usage_duration": "",
  "created_at": "2025-03-05T04:40:27.177384Z",
  "updated_at": "2025-03-05T04:40:27.177384Z"
}

3. View Your Workstation​

You can leverage our Web UI at app.agentstation.ai to see all your active workstations and manage them or you can connect directly through multiple protocols such as VNC, CDP and more.

4. Perform a Google Search with an AI Browser Operator​

Open a new browser tab and navigate to google.com

curl -L "https://api.agentstation.ai/v1/workstations/$WORKSTATION_ID/browser/tabs" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $AGENTSTATION_API_KEY" \
-d '{
  "url": "https://www.google.com/"
}'

Perform a search and click on result links via an AI browser operator

curl -L "https://api.agentstation.ai/v1/workstations/$WORKSTATION_ID/browser/prompt" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $AGENTSTATION_API_KEY" \
-d '{
  "prompt": "search for 'agentstation.ai', press 'enter', and click on the first result"
}'

5. Release Workstation​

Finally, you can release the workstation using the Release workstation endpoint:

curl -L -X DELETE "https://api.agentstation.ai/v1/workstations/$WORKSTATION_ID" \
-H "Authorization: Bearer $AGENTSTATION_API_KEY"

You should receive a 204 response indicating that the workstation has been released.

6. Advanced Extra Credit - Connect via local VNC Client​

If you want to connect directly to a workstation via VNC, we recommend the TigerVNC client to connect to your workstation.

First, download and install the appropriate binary from the Github releases page.

Next, you can make a request to get a VNC connection url.

curl -X POST "https://api.agentstation.ai/v1/workstations/$WORKSTATION_ID/vnc" \
  -H "Authorization: Bearer $AGENTSTATION_API_KEY"

You should recieve a JSON payload that looks like the following on success:

{
  "url": "yo9zlyiklfzx.vnc.v1.connect.agentstation.ai:5900",
  "protocol": "vnc"
}

To use this URL to connect over VNC you will need run two different commands in two different terminal tabs. The first command requires socat, if you don't have it installed you can do so via homebrew brew install socat if on a Mac.

Terminal Tab #1:

socat TCP-LISTEN:5901,reuseaddr,fork EXEC:'socat - "SSL:yo9zlyiklfzx.vnc.v1.connect.agentstation.ai:5900"'

Terminal Tab #2:

vncviewer -SecurityTypes=None localhost:5901

On successful connection, you should see a desktop open or become available in your application bar. Your very own virtual workstation! You can move your mouse around and interact with the desktop just like any other computer.

Next Steps​

This quickstart runs through the basics of using the API to request a workstation, take actions, and release that workstation back.

To build more autonomous agents, we recommend reading the Levels of Autonomy guide to get a broader understanding of how AgentStation can be used with AI models to drive workstation actions, as well as how to build "human-in-the-loop" capabilities into your application.