← Antigravity Manager guides

API & CONFIGURATION · ANTIGRAVITY TOOLS

Antigravity Manager API & Configuration Reference

Find the endpoint, credential and request format for your integration. Antigravity Manager serves AI requests and its management API on one port, with separate authentication rules.

For stable v5.0.0. Beta additions are labeled below. Updated .

Which base URL and credential should I use?

Use your Manager host and port, normally http://127.0.0.1:8045. AI routes and /api management routes share this listener. Docker port mapping can change the port you use from outside the container.

For an OpenAI-compatible client that appends /chat/completions, set its base URL to http://127.0.0.1:8045/v1. The tables below show full paths to append to the origin. See client-specific base URLs or Docker networking for your setup.

RequestCredential
AI routesproxy.api_key or a user API token, sent as Authorization: Bearer ….
Management routesproxy.admin_password, sent as Bearer. When this password is empty, Manager uses proxy.api_key. User API tokens have access to AI routes only.

Both authentication paths recognize credentials in this order: Authorization, x-api-key, x-goog-api-key, then ?key=. Send one credential header per request. Use Bearer authentication in scripts; query keys can appear in URL logs. The older x-admin-token header is unsupported in 5.0.0.

Auth modes and public probes
strict
Require a valid AI credential, including for health, version and properties probes.
all_except_health
Require an AI credential except on /health, /healthz, /version, /v1/version, /props and /v1/props.
off
Accept AI requests without authentication.
auto
Resolve to off when LAN access is false, or all_except_health when LAN access is true.

GET /api/health is public in all four modes. Other management routes retain admin authentication. CORS preflight OPTIONS bypasses authentication. IP filters and the AI service state can still affect requests independently.

Headless startup changes a saved off or auto to all_except_health before applying any explicit environment override. See access controls and token revocation before exposing a shared instance.

API endpoints in v5.0.0

Append one of these paths to your Manager origin. Replace {model} with a model ID and {id} with the resource ID returned by Manager.

AI gateway

Method and pathUse and response
GET/health · /healthzListener probes. Check /api/proxy/status for the AI service state.
GET/version · /v1/version · /props · /v1/propsVersion and compatibility properties; same auth exemptions as health probes.
GET/v1/modelsModel list; choose a returned data[].id.
GET/v1/models/{model}One model’s metadata. Alias: /v1/model/{model}.
POST/v1/chat/completionsChat messages; JSON or SSE with stream: true.
POST/v1/completionsLegacy request adapter; returns a Chat-shaped result in this version.
POST/v1/responsesResponses request; input array, JSON or SSE output.
GET/v1/responsesWebSocket upgrade; requires WebSocket handshake headers.
GET/v1/responses/models · /v1/responses/models/{model}Responses model metadata.
POST/v1/images/generations · /v1/images/editsGenerate or edit images; edits accepts multipart form data.
POST/v1/audio/transcriptionsMultipart audio transcription; returns JSON with text.
POST/v1/messages · /v1/messages/count_tokensAnthropic-compatible messages and token counting.
GET/v1/models/claude · /v1/models/claude/{model}Claude-compatible model metadata.
GET/v1beta/models · /v1beta/models/{model}Gemini-compatible model list and metadata.
POST/v1beta/models/{model}:generateContentGemini content generation.
POST/v1beta/models/{model}:streamGenerateContentGemini streaming content generation.
POST/v1beta/models/{model}:countTokensToken count. Also accepts /v1beta/models/{model}/countTokens.

Compatibility aliases also include POST /responses, POST /responses/compact, and GET /responses/models or /responses/models/{model}. The compact alias enters the Responses handler. For actual context compression behavior, use the compaction guide.

For image fields, multipart uploads and media limits, use the image, audio and video guide.

Common management endpoints

Use the admin credential for every row except /api/health. Token creation/listing and configuration reads return secrets; keep those responses private.

Method and pathUse and response
GET/api/healthPublic health probe.
GET/api/accounts · /api/accounts/currentAccount summaries / current account.
POST/api/accounts/switchBody: accountId, optional targetIde. Successful switch: 200, empty body.
POST/api/accounts/refreshRefresh quotas; returns JSON statistics after processing.
GET/api/configFull application configuration, including credentials.
POST/api/configSave full configuration inside the config wrapper; 200, empty body.
GET/api/proxy/statusCurrent AI service state, port and statistics.
POST/api/proxy/start · /api/proxy/stopEnable or disable AI service handling on the existing listener.
GET/api/system/data-dirResolved data directory as a JSON string.
GET/api/user-tokensUser token array, including token values.
POST/api/user-tokensCreate a token; returns the new token object.
PATCH/api/user-tokens/{id}Update selected token fields; 200, empty body.
DELETE/api/user-tokens/{id}Delete a token; 204, empty body.
POST/api/user-tokens/{id}/renewBody: expiresType; 200, empty body.
GET/api/logs · /api/logs/count · /api/logs/{id}Filtered traffic list, count and record detail.
GET/api/stats/token/summary · /api/stats/token/by-modelToken usage summaries.

Stopping the AI service leaves management reachable. /health can still return 200, so use /api/proxy/status to read running. A disabled AI service returns 503 for generation requests and /healthz. Full log filters and storage controls are in diagnostics; the versioned route registry includes additional administration operations.

Send a request and read its output

Use messages for Chat Completions and an input array for Responses. Select a model from your instance and start with a short, non-streaming request.

These commands use Bash, curl with --fail-with-body support, and jq. Run them in macOS/Linux Bash or Windows WSL/Git Bash. Change BASE_URL for a remote instance. The key prompt hides your input.

Bash · connection
BASE_URL='http://127.0.0.1:8045'
read -r -s -p 'Proxy API key: ' API_KEY; printf '\n'
List models
curl -sS --fail-with-body "$BASE_URL/v1/models" \
  -H "Authorization: Bearer $API_KEY"
Chat Completions
read -r -p 'Model ID from the catalog: ' MODEL_ID
jq -n --arg model "$MODEL_ID" \
  '{model: $model, messages: [{role: "user", content: "Reply with hello."}], stream: false}' |
curl -sS --fail-with-body "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' --data-binary @-

Read chat text from choices[].message.content. A tool request appears in choices[].message.tool_calls. The client executes each tool and sends its result in the next request; see the tool-call round trip.

Responses · use the same MODEL_ID
jq -n --arg model "$MODEL_ID" \
  '{model: $model, input: [{role: "user", content: "Reply with hello."}], stream: false}' |
curl -sS --fail-with-body "$BASE_URL/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' --data-binary @-

A successful non-streaming Responses result has object: "response", an id, status and an output array. Each output item has its own type: message, reasoning or function_call. Read text from message content blocks whose type is output_text; reasoning may appear first in the array.

Extract text, handle streaming and continue a conversation

To save a response, add -o response.json to the Responses curl command. Then extract its text:

Read message text with jq
jq -r '.output[]? | select(.type == "message") | .content[]? | select(.type == "output_text") | .text' response.json

If extraction returns no text, inspect status, error and output item types. A function_call needs execution by the client and a matching function_call_output carrying the same call_id. Refusal content also needs separate handling.

With stream: true, read SSE events and text deltas until the response’s terminal event. For a WebSocket client, connect to GET /v1/responses with an upgrade handshake and send a response.create event. An ordinary GET on that URL cannot retrieve a saved response.

previous_response_id can restore conversation history held by the running Manager process. Keep your own conversation history for recovery after a restart or session expiry. The route registry has no GET /v1/responses/{id} retrieval endpoint. Setting store: false prevents saving the new turn in this session store; traffic payload logging has separate settings.

Models, routing and HTTP errors

Choose a returned model ID, then send a small request to check access with your account pool. Available quota, account eligibility and routing rules determine which requests can complete.

X-Mapped-Model and X-Upstream-Model, when returned, help trace routing decisions. Save them with the HTTP status and error body when troubleshooting. Use model selection and mappings for exact aliases and account restrictions.

Status or symptomWhat to check
401Missing AI credential or failed admin authentication. Check the credential type and header.
403Rejected AI token, IP rule, or upstream access restriction. Read the body before changing credentials.
400 / 422Invalid JSON fields, incompatible content or parameter types. 422 can come from request deserialization.
404 / 405Wrong path, unavailable model metadata, or wrong HTTP method. A 200 HTML page on an unknown path can be the Web UI fallback.
413Body or media limit exceeded; check both the server limit and the endpoint’s file limit.
429 / 503Rate limit, exhausted or unavailable account pool, or disabled AI service. Follow quota and pool diagnostics.
5xx / interrupted streamRead the upstream error and determine the failing phase with streaming diagnostics.

Error bodies vary: an admin failure may contain an error string, an AI error may contain a nested error object, and middleware can return an empty body. Check HTTP status and Content-Type before parsing JSON. Empty bodies are expected after several successful management writes.

Configuration fields and environment variables

GET /api/config returns the full application configuration. POST /api/config saves a full configuration under the config key. Preserve the complete object when making changes.

FieldMeaning
proxy.enabled / proxy.auto_startSaved AI service state / automatic start preference. Use the start and stop endpoints for immediate control.
proxy.portListener port; default 8045. Plan a listener restart for port or bind-address changes.
proxy.allow_lan_accessFalse: loopback. True: wildcard binding for network access.
proxy.api_key / proxy.admin_passwordAI key / independent admin password. Credential changes take effect for subsequent requests.
proxy.auth_modeThe four authentication modes.
proxy.custom_mappingObject mapping client model names to target model names.
proxy.request_timeoutRequest timeout setting in seconds, default 120; individual connection and stream stages have their own budgets.
proxy.stream_timeoutsinitial_ttft_secs, transition_secs, streaming_sliding_secs.
language, theme, auto_refresh, refresh_intervalApp preferences; refresh interval is in minutes.
Read, edit and verify a full configuration with Bash and jq

Run the connection setup above first. Use a private working directory: the saved files contain credentials. The following creates a new directory, retains the original and prepares a separate editable copy.

Save the original configuration
read -r -s -p 'Admin password: ' ADMIN_PASSWORD; printf '\n'
umask 077
CONFIG_DIR=$(mktemp -d ./manager-config.XXXXXX)
curl -sS --fail-with-body "$BASE_URL/api/config" \
  -H "Authorization: Bearer $ADMIN_PASSWORD" \
  -o "$CONFIG_DIR/config-original.json" &&
jq -e 'type == "object" and (.proxy | type == "object")' \
  "$CONFIG_DIR/config-original.json" >/dev/null &&
cp "$CONFIG_DIR/config-original.json" "$CONFIG_DIR/config-edited.json"

Continue only after that command succeeds. Edit config-edited.json in the directory held in CONFIG_DIR, preserving unrelated fields. Then wrap the complete object and save:

Save the edited configuration
jq -e '{config: .}' "$CONFIG_DIR/config-edited.json" > "$CONFIG_DIR/request.json" &&
curl -sS --fail-with-body "$BASE_URL/api/config" \
  -H "Authorization: Bearer $ADMIN_PASSWORD" \
  -H 'Content-Type: application/json' \
  --data-binary @"$CONFIG_DIR/request.json" -w '\nHTTP %{http_code}\n'

Expect HTTP 200 with an empty body. If you changed the admin password, update ADMIN_PASSWORD before reading back. Compare the saved configuration:

Read back and compare
curl -sS --fail-with-body "$BASE_URL/api/config" \
  -H "Authorization: Bearer $ADMIN_PASSWORD" \
  -o "$CONFIG_DIR/config-after.json" &&
diff -u <(jq -S . "$CONFIG_DIR/config-edited.json") \
  <(jq -S . "$CONFIG_DIR/config-after.json")

A clean comparison prints nothing. To restore the original settings, repeat the save step with config-original.json in place of config-edited.json, using the currently valid credential. Coordinate changes with other administrators to avoid replacing each other’s edits. Keep or remove these local files according to your backup policy.

Environment overrides in stable v5.0.0

The first four rows below apply at headless startup. For paired names, the ABV_ variable takes precedence over the unprefixed name. A blank prefixed key/password suppresses the fallback variable and leaves the saved value in place. Accepted key/password/auth overrides are saved to the configuration.

VariableEffect
ABV_API_KEY / API_KEYOverride the AI key.
ABV_WEB_PASSWORD / WEB_PASSWORDOverride the admin password.
ABV_AUTH_MODE / AUTH_MODESet off, strict, all_except_health or auto after the headless startup policy is applied.
ABV_BIND_LOCAL_ONLYValues 1, true, yes or on select loopback binding; headless otherwise enables network binding.
ABV_DATA_DIROverride the application data directory. Read the resolved path from GET /api/system/data-dir.
ABV_MAX_BODY_SIZEServer request-body limit in bytes; default 104857600 (100 MiB). Endpoint-specific media limits still apply.
ABV_PUBLIC_URLBase for the Web OAuth redirect: Manager appends /auth/callback. The default is http://localhost:PORT/auth/callback. The OAuth client must permit the resulting redirect URI.

Changing environment variables requires restarting the process with the new values. For remote login, follow Docker OAuth setup; for connection failures, use the connection checklist.

Stable stream timeout variables

These three variables already work in v5.0.0. They override the corresponding stream timeout settings.

Variable and defaultStage
ANTIGRAVITY_TIMEOUT_TTFT_SECS180 secondsWait for the first meaningful stream content.
ANTIGRAVITY_TIMEOUT_TRANSITION_SECS180 secondsWait between stream phases, such as thinking and answer text.
ANTIGRAVITY_TIMEOUT_STREAMING_SECS120 secondsSliding timeout during stream output.

Use the timeout troubleshooting sequence to identify the stage before increasing its budget.

Storage fields

The default data directory is ~/.antigravity_tools in your user home. Custom, portable and Docker installations can resolve elsewhere. gui_config.json stores app settings; account records contain OAuth tokens and quota metadata; SQLite files store traffic, usage and user tokens. Use data paths and backup instructions for the complete file map. Keep direct file edits to a stopped application and retain a backup.

Create, update and revoke user API tokens

Create a user credential with POST /api/user-tokens using your admin password. The response includes the resource id for management operations and the secret token for AI requests.

JSON body · create a token lasting one week
{
  "username": "Work laptop",
  "expires_type": "week",
  "max_ips": 0
}
Create fieldValue
usernameRequired label identifying the user or client.
expires_typeRequired: day, week, month (30 days), never or custom. Use exact spelling.
custom_expires_atFor custom expiry, supply a Unix timestamp in seconds.
max_ipsRequired integer; 0 allows unlimited IPs, a positive number caps distinct bound IPs.
descriptionOptional label or note.
curfew_start / curfew_endOptional blocked interval in HH:MM, using UTC+8. Both values are needed; an interval can cross midnight.

PATCH /api/user-tokens/{id} accepts selected username, description, enabled, max_ips and curfew fields. Renewal uses a different spelling: POST /api/user-tokens/{id}/renew with {"expiresType":"week"}. Read the token list afterward to confirm the resulting expiry.

Revoke a token with DELETE. In v5.0.0, setting enabled: false still allows that token to authenticate on /v1/models. Deleting it rejects the old value when AI authentication is required. With auth_mode: off, AI access stays open regardless of token deletion. Follow the revocation procedure for a shared instance.

Token list responses also include expiry, creation/update/last-use timestamps and request/token counters. Keep the returned token values out of bug reports. For account OAuth credentials, use account management.

How do I know a management operation finished?

Wait for the HTTP response, then read back the affected resource. In v5.0.0, account switching waits for the operation and returns 200 with an empty body on success; quota refresh returns its statistics as JSON.

If the client times out during a write, check the current state before retrying. The server may have completed the operation while the client stopped waiting. For a switch, read /api/accounts/current; for configuration, read /api/config.

For 202 Accepted, first identify the responding server and build. The old 19527 HTTP interface documented that response, but the active 5.0.0 management routes provide no task ID or generic task-status polling URL. Use the normal response and read-back sequence above.

Beta additions and removed features

Match these features to the version you run. Stable 5.0.0 includes the routes and three stream timeout variables above; the following additions belong to later beta releases.

v5.0.1-beta.2: terminal client sync

antigravity-tools sync writes client configuration on the computer running the command. For Claude Code, choose a model available through your instance, set MODEL_ID as in the request example, and run:

Beta.2 · writes local Claude Code configuration
antigravity-tools sync claude --model "$MODEL_ID"

The command reads the saved Manager port and key and writes a loopback base URL. Running it inside a container changes files there; a client on another computer needs a reachable host in its own configuration. Back up client settings first and use Claude Code setup and restore for the resulting configuration. Stable users can use the existing UI sync workflow.

v5.0.1-beta.4: connection and upload timeout variables

These seven variables extend timeout control in beta.4. Values below are defaults before configuration or environment overrides.

Variable and defaultEffect
ANTIGRAVITY_TIMEOUT_CONNECT_SECS10 secondsPer-endpoint connection limit; restart the proxy after changing it.
ANTIGRAVITY_TIMEOUT_UPLOAD_MIN_MBPS2 MbpsBandwidth estimate for the upload budget.
ANTIGRAVITY_TIMEOUT_UPLOAD_EXTRA_WAIT_RATIO0.4Extra allowance: estimated upload time × (1 + ratio).
ANTIGRAVITY_TIMEOUT_UPLOAD_STALL_SECS45 secondsUpload inactivity limit, bounded by the total upload budget.
ANTIGRAVITY_TIMEOUT_HEADER_WAIT_SECS0Use the built-in scenario budget; a positive value overrides it in seconds.
ANTIGRAVITY_TIMEOUT_LARGE_BODY_MB8 MiBPayload threshold for the large-body retry policy.
ANTIGRAVITY_TIMEOUT_LARGE_BODY_ENDPOINT_ATTEMPTS1 attemptEndpoint attempt cap for a large upload.

The upload bandwidth setting uses megabits per second. To calculate a time allowance, convert payload size to bits first. Endpoint attempts and separate stream budgets can affect total elapsed time.

Built-in z.ai and local MCP removal

The built-in z.ai provider dispatch and local MCP Search/Reader/Vision server were removed in 4.8.6-beta.8. Stable 5.0.0 therefore has no setup card or route for those services. An external MCP-capable client can still execute its own tools and exchange tool definitions/results through a supported AI endpoint. See tool-call troubleshooting.

Version details: routes and management handlers, authentication, proxy configuration, Responses handling, and beta.4 timeout configuration. For a first connection, return to API Proxy setup.

WINDOWS DOWNLOAD

Archive password

Keep this password to open your Windows download if prompted.