Reference

REST API

The CLI and SDK use a public JSON API. Call it directly to automate GFT from any language.

Base URL and authentication#

Every request goes to one origin, https://studio.g-ftech.com. Send your API key as a bearer token:

bash

curl https://studio.g-ftech.com/v1/me -H "Authorization: Bearer $GFT_API_KEY"

The Scope column below shows the API key scope each endpoint needs. See Authentication.

Send X-Request-ID to trace a request. Error responses include the request ID.
Send Idempotency-Key when you create a run, an evaluation or a deployment. A retry with the same key and body does not create a second one; a different body returns IDEMPOTENCY_PAYLOAD_CONFLICT.
Retry 429, 502, 503 and 504 responses with backoff.

Errors use one JSON format. See Errors and exit codes.

Method	Endpoint	Scope	Description
GET	`/health`	Public	Check that the API is up.
GET	`/v1/auth/config`	Public	List the sign-in methods enabled on this server.
POST	`/v1/auth/session`	Bootstrap	Exchange an issued credential for an HttpOnly browser session.
POST	`/v1/auth/development-session`	Local only	Create the loopback-only development session.
GET	`/v1/me`	Any key	Return the current user and organization.
PATCH	`/v1/me`	Browser session	Update the current user's display name.
POST	`/v1/billing/invite-codes/redeem`	Browser session	Redeem a one-time invite code into the current workspace's credits.
GET	`/v1/studio/catalog`	Browser session	List the models, gyms, recipes, exact revisions and qualification flags that Studio uses for managed training.

Method	Endpoint	Scope	Description
GET	`/v1/environments`	`read`	Search and filter your organization's Environment Hub.
POST	`/v1/environments`	`publish`	Validate, qualify and publish one private gym version.
POST	`/v1/environments/push`	`publish`	Upload a wheel and queue an isolated sandbox build.
GET	`/v1/environments/{environment_id}`	`read`	Inspect one gym, its readiness and schemas.

Method	Endpoint	Scope	Description
POST	`/v1/plans`	`run` or `benchmark`	Pin the gym versions selected by a slug.
POST	`/v1/runs`	`run`	Accept one training run from a resolved plan.
GET	`/v1/runs/{run_id}`	`read`	Read the training status.
POST	`/v1/runs/{run_id}/cancel`	`run`	Cancel a training run. Safe to repeat.
POST	`/v1/benchmarks/submit`	`benchmark`	Submit one evaluation. It runs in the background.
GET	`/v1/operations/{operation_id}`	`read`	Read evaluation status and results.
POST	`/v1/operations/{operation_id}/cancel`	`benchmark`	Cancel an evaluation that is still queued.

Method	Endpoint	Scope	Description
GET	`/v1/models`	`inference`	List the inference models available to your organization.
GET	`/v1/serving/deployments`	`read`	List inference deployments.
GET	`/v1/serving/deployments/{deployment_id}`	`read`	Inspect one deployment.
POST	`/v1/serving/deployments`	`deploy`	Provision a promoted model artifact.
POST	`/v1/serving/deployments/{deployment_id}/canary`	`deploy`	Run the activation canary.
POST	`/v1/serving/deployments/{deployment_id}/activate`	`deploy`	Activate a deployment that passed its canary.

Method	Endpoint	Scope	Description
GET, POST	`/v1/images`	`read`, `run`	List or register workspace images by immutable digest.
GET	`/v1/containers/capabilities`	`read`	Read container availability, modes and tariffs.
GET, POST	`/v1/containers`	`read`, `run`	List containers, or start one within your budget limits.
GET	`/v1/containers/{id}`	`read`	Read the machine lifecycle and process status.
GET	`/v1/containers/{id}/logs`	`read`	Read a bounded tail of the logs.
GET	`/v1/containers/{id}/outputs`	`read`	Get a temporary download URL for saved outputs.
POST	`/v1/containers/{id}/http`	`run`	Send one bounded HTTP request to a service. No streaming or WebSockets.
POST	`/v1/containers/{id}/terminals`	`run`	Open an interactive terminal session.
WS	`/v1/containers/{id}/terminals/{session}/ws`	`run`	Attach to the terminal over WSS.
DELETE	`/v1/containers/{id}/terminals/{session}`	`run`	End the terminal session.
POST	`/v1/containers/{id}/stop`	`run`	Delete the machine and its temporary disk.

An MCP server is not available yet. When it ships, it will use the same API keys and scopes.