Skip to main content

​
Quickstart (cURL)

This guide will walk you through a complete, end-to-end example of using the WithGiga API to instantly provision a cloud computer and instruct an AI agent to complete a task.

​
Prerequisites

Before starting, make sure you have:
  • An active WithGiga API Key (starts with giga_sk_...)
  • curl installed on your terminal

​
Step 1: Start a Deployment and AI Run

We will use the /api/deployments/start endpoint. This is a powerful, unified endpoint that:
  1. Provisions a new virtual computer (sandbox).
  2. Initializes an AI session.
  3. Automatically triggers the AI agent to begin executing your instructions.
To instruct the agent, we set "aiEnabled": true and provide a prompts object with a userPrompt (what to do) and a goalPrompt (what constitutes success). 
curl -X POST https://api.withgiga.ai/api/deployments/start \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HackerNews Data Extractor",
    "platform": "giga-standard",
    "duration": 1,
    "aiEnabled": true,
    "prompts": {
      "userPrompt": "Navigate to https://news.ycombinator.com and find the top article.",
      "goalPrompt": "Save the title of the top article into a file called hn_top.txt on the Desktop.",
      "systemPrompt": "You are a precise data extraction bot."
    }
  }'
Expected Response: 
{
  "success": true,
  "message": "Deployment created and session initialized successfully",
  "data": {
    "deployment": {
      "id": "dep_12345",
      "name": "HackerNews Data Extractor",
      "status": "provisioning",
      "platform": "giga-standard",
      "createdAt": "2024-03-16T12:00:00.000Z"
    },
    "session": {
      "threadId": "3b2a1f9c-...",
      "messageId": "msg_abc123",
      "sandboxId": "sbx_789",
      "vncUrl": "wss://..."
    }
  }
}
Save the deployment.id from this response, as you will use it to check the status of your computer.

​
Step 2: Poll Deployment Status

The computer provisioning and agent execution happen asynchronously in the background. You can poll the Deployment endpoint to check the overall status of the machine. 
curl -X GET "https://api.withgiga.ai/api/deployments/{deployment.id}" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"
Example Response (Provisioning): 
{
  "success": true,
  "data": {
    "deployment": {
      "id": "dep_12345",
      "status": "provisioning"
    }
  }
}
Example Response (Running): Once the sandbox is fully booted and the AI agent is actively working, the status will change to running. 
{
  "success": true,
  "data": {
    "deployment": {
      "id": "dep_12345",
      "status": "running",
      "metadata": {
        "sandboxId": "sbx_789",
        "vncUrl": "wss://...",
        "threadId": "3b2a1f9c-..."
      }
    }
  }
}
Once the agent successfully finishes the goal, status will change to COMPLETED and isCompleted will be true.