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.
| Request | Credential |
|---|---|
| AI routes | proxy.api_key or a user API token, sent as Authorization: Bearer …. |
| Management routes | proxy.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,/propsand/v1/props. off- Accept AI requests without authentication.
auto- Resolve to
offwhen LAN access is false, orall_except_healthwhen 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 path | Use and response |
|---|---|
GET/health · /healthz | Listener probes. Check /api/proxy/status for the AI service state. |
GET/version · /v1/version · /props · /v1/props | Version and compatibility properties; same auth exemptions as health probes. |
GET/v1/models | Model list; choose a returned data[].id. |
GET/v1/models/{model} | One model’s metadata. Alias: /v1/model/{model}. |
POST/v1/chat/completions | Chat messages; JSON or SSE with stream: true. |
POST/v1/completions | Legacy request adapter; returns a Chat-shaped result in this version. |
POST/v1/responses | Responses request; input array, JSON or SSE output. |
GET/v1/responses | WebSocket upgrade; requires WebSocket handshake headers. |
GET/v1/responses/models · /v1/responses/models/{model} | Responses model metadata. |
POST/v1/images/generations · /v1/images/edits | Generate or edit images; edits accepts multipart form data. |
POST/v1/audio/transcriptions | Multipart audio transcription; returns JSON with text. |
POST/v1/messages · /v1/messages/count_tokens | Anthropic-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}:generateContent | Gemini content generation. |
POST/v1beta/models/{model}:streamGenerateContent | Gemini streaming content generation. |
POST/v1beta/models/{model}:countTokens | Token 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 path | Use and response |
|---|---|
GET/api/health | Public health probe. |
GET/api/accounts · /api/accounts/current | Account summaries / current account. |
POST/api/accounts/switch | Body: accountId, optional targetIde. Successful switch: 200, empty body. |
POST/api/accounts/refresh | Refresh quotas; returns JSON statistics after processing. |
GET/api/config | Full application configuration, including credentials. |
POST/api/config | Save full configuration inside the config wrapper; 200, empty body. |
GET/api/proxy/status | Current AI service state, port and statistics. |
POST/api/proxy/start · /api/proxy/stop | Enable or disable AI service handling on the existing listener. |
GET/api/system/data-dir | Resolved data directory as a JSON string. |
GET/api/user-tokens | User token array, including token values. |
POST/api/user-tokens | Create 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}/renew | Body: 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-model | Token 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.
BASE_URL='http://127.0.0.1:8045'
read -r -s -p 'Proxy API key: ' API_KEY; printf '\n'curl -sS --fail-with-body "$BASE_URL/v1/models" \
-H "Authorization: Bearer $API_KEY"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.
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:
jq -r '.output[]? | select(.type == "message") | .content[]? | select(.type == "output_text") | .text' response.jsonIf 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 symptom | What to check |
|---|---|
| 401 | Missing AI credential or failed admin authentication. Check the credential type and header. |
| 403 | Rejected AI token, IP rule, or upstream access restriction. Read the body before changing credentials. |
| 400 / 422 | Invalid JSON fields, incompatible content or parameter types. 422 can come from request deserialization. |
| 404 / 405 | Wrong path, unavailable model metadata, or wrong HTTP method. A 200 HTML page on an unknown path can be the Web UI fallback. |
| 413 | Body or media limit exceeded; check both the server limit and the endpoint’s file limit. |
| 429 / 503 | Rate limit, exhausted or unavailable account pool, or disabled AI service. Follow quota and pool diagnostics. |
| 5xx / interrupted stream | Read 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.
| Field | Meaning |
|---|---|
proxy.enabled / proxy.auto_start | Saved AI service state / automatic start preference. Use the start and stop endpoints for immediate control. |
proxy.port | Listener port; default 8045. Plan a listener restart for port or bind-address changes. |
proxy.allow_lan_access | False: loopback. True: wildcard binding for network access. |
proxy.api_key / proxy.admin_password | AI key / independent admin password. Credential changes take effect for subsequent requests. |
proxy.auth_mode | The four authentication modes. |
proxy.custom_mapping | Object mapping client model names to target model names. |
proxy.request_timeout | Request timeout setting in seconds, default 120; individual connection and stream stages have their own budgets. |
proxy.stream_timeouts | initial_ttft_secs, transition_secs, streaming_sliding_secs. |
language, theme, auto_refresh, refresh_interval | App 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.
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:
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:
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.
| Variable | Effect |
|---|---|
ABV_API_KEY / API_KEY | Override the AI key. |
ABV_WEB_PASSWORD / WEB_PASSWORD | Override the admin password. |
ABV_AUTH_MODE / AUTH_MODE | Set off, strict, all_except_health or auto after the headless startup policy is applied. |
ABV_BIND_LOCAL_ONLY | Values 1, true, yes or on select loopback binding; headless otherwise enables network binding. |
ABV_DATA_DIR | Override the application data directory. Read the resolved path from GET /api/system/data-dir. |
ABV_MAX_BODY_SIZE | Server request-body limit in bytes; default 104857600 (100 MiB). Endpoint-specific media limits still apply. |
ABV_PUBLIC_URL | Base 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 default | Stage |
|---|---|
ANTIGRAVITY_TIMEOUT_TTFT_SECS180 seconds | Wait for the first meaningful stream content. |
ANTIGRAVITY_TIMEOUT_TRANSITION_SECS180 seconds | Wait between stream phases, such as thinking and answer text. |
ANTIGRAVITY_TIMEOUT_STREAMING_SECS120 seconds | Sliding 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.
{
"username": "Work laptop",
"expires_type": "week",
"max_ips": 0
}| Create field | Value |
|---|---|
username | Required label identifying the user or client. |
expires_type | Required: day, week, month (30 days), never or custom. Use exact spelling. |
custom_expires_at | For custom expiry, supply a Unix timestamp in seconds. |
max_ips | Required integer; 0 allows unlimited IPs, a positive number caps distinct bound IPs. |
description | Optional label or note. |
curfew_start / curfew_end | Optional 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:
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 default | Effect |
|---|---|
ANTIGRAVITY_TIMEOUT_CONNECT_SECS10 seconds | Per-endpoint connection limit; restart the proxy after changing it. |
ANTIGRAVITY_TIMEOUT_UPLOAD_MIN_MBPS2 Mbps | Bandwidth estimate for the upload budget. |
ANTIGRAVITY_TIMEOUT_UPLOAD_EXTRA_WAIT_RATIO0.4 | Extra allowance: estimated upload time × (1 + ratio). |
ANTIGRAVITY_TIMEOUT_UPLOAD_STALL_SECS45 seconds | Upload inactivity limit, bounded by the total upload budget. |
ANTIGRAVITY_TIMEOUT_HEADER_WAIT_SECS0 | Use the built-in scenario budget; a positive value overrides it in seconds. |
ANTIGRAVITY_TIMEOUT_LARGE_BODY_MB8 MiB | Payload threshold for the large-body retry policy. |
ANTIGRAVITY_TIMEOUT_LARGE_BODY_ENDPOINT_ATTEMPTS1 attempt | Endpoint 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.