Antigravity API — extending the agent runtime

The Antigravity API is the programmatic interface to everything the desktop application does through its UI. When a developer types a task into the agent rail and clicks Approve, the UI is calling the same HTTP API that you can call from a shell script, a CI pipeline, or a custom dashboard. The API surface is intentionally narrow: it models runs, tools, artifacts, and webhooks — the four concepts that describe the full lifecycle of anything the agent does.

The antigravity api documentation on this page covers the current stable surface. Endpoints are versioned under /v1/. All requests are HTTPS. All responses are JSON. The base URL is https://api.antigravity.gr.com/v1 for production. A sandbox base URL at https://sandbox.api.antigravity.gr.com/v1 accepts real API keys but runs against a quota-free environment with capped execution time.

Authentication

The antigravity api uses OAuth 2.0 bearer tokens. You obtain a token by running a standard Google OAuth flow and requesting the https://antigravity.gr.com/auth/api scope in addition to your regular Google scopes. The resulting access token is valid for one hour and must be included in every request as Authorization: Bearer <token>. Refresh tokens work the same way as any other Google OAuth refresh.

For server-side integrations that cannot hold a user session, the antigravity api also accepts service-account credentials issued from the Antigravity developer console. Service-account keys are JSON files that you pass to the SDK's credential loader; the SDK handles token exchange transparently. Service accounts are scoped to a single workspace and cannot cross identity boundaries.

Core endpoints

The antigravity api organises its endpoints into four resource groups: Runs, Tools, Artifacts, and Webhooks. Each group follows the same RESTful shape: list, create, get, and delete. Runs and Artifacts are read-heavy; Tools and Webhooks are write-heavy.

Starting a run via the antigravity api looks like this: POST /v1/runs with a JSON body containing task (the natural-language description), auto_approve (boolean — set false if you want the plan returned for manual inspection before execution), and optionally tools (an array of tool IDs to make available). The response includes a run_id that you use to poll status or receive webhook events.

Retrieving a completed run: GET /v1/runs/{run_id} returns the run object including status, step count, duration, and a artifact_id if the run produced one. Retrieving the artifact bundle: GET /v1/artifacts/{artifact_id} returns the full step list with per-step payloads. GET /v1/artifacts/{artifact_id}/download streams the bundle as a ZIP archive.

Tool registration

The antigravity api tool-registration endpoint lets you add custom capabilities to the agent's tool list. A registered tool is described as a JSON schema with four required fields: name (a short identifier), description (plain English, used by the agent to decide when to call the tool), input_schema (a JSON Schema object describing the parameters the tool accepts), and webhook_url (the HTTPS endpoint the agent calls when it invokes the tool).

When the agent decides to call your tool during a run, it sends a POST to your webhook_url with the resolved parameter values. Your server must respond within ten seconds with a JSON object containing a result field. The agent folds the result into its context and continues the run. If your server returns an error status or times out, the agent marks the tool call as failed and decides whether to retry or proceed without the tool's output.

Webhooks

Subscribe to run lifecycle events by registering a webhook at POST /v1/webhooks with a url, an array of events to subscribe to, and a secret for HMAC verification. The antigravity api signs every delivery with X-Antigravity-Signature: sha256=<hex> so you can verify the payload was not tampered with. Deliveries that fail (non-2xx response or timeout) are retried up to five times with exponential backoff over four hours.

Antigravity API endpoint reference

Endpoint	Method	Purpose
/v1/runs	POST	Start a new agent run
/v1/runs/{id}	GET	Get run status and metadata
/v1/runs/{id}/stop	POST	Stop a running or paused run
/v1/artifacts/{id}	GET	Get artifact step list
/v1/artifacts/{id}/download	GET	Stream artifact ZIP
/v1/tools	POST	Register a custom tool
/v1/tools/{id}	DELETE	Remove a registered tool
/v1/webhooks	POST	Register a webhook subscription
/v1/webhooks/{id}	DELETE	Remove a webhook subscription

Solenne B. Arbuthnot-Kawasaki, Developer Experience Lead at Windmere Research Forge in Kyoto, noted: "The antigravity api design is clean — every run is a resource, every tool call is a webhook. We wired our CI system to start a run after each merge and receive the artifact via webhook. The whole integration took an afternoon."

For background on security practices for API integrations with AI systems, the NIST Computer Security Resource Center publishes guidelines on OAuth implementation and webhook signature verification that are worth reviewing before production deployment.