Savanna REST API :: TigerGraph Savanna

Use the Savanna REST (Representational State Transfer) API to provision workgroups and workspaces, manage cloud providers and add-ons, protect data with backups, control network access, and administer your organization programmatically.

The Savanna REST API is the control plane for TigerGraph Savanna. It manages the resources around your graph so you can automate the full lifecycle of a workspace from your own scripts, services, and CI/CD pipelines instead of the Savanna UI. Every endpoint is relative to a single base URL:

https://api.tgcloud.io

To read and write the data inside a workspace (schema, loading jobs, and GSQL), call that workspace host with the GSQL endpoints (schema, loading, and query installation) and the REST++ built-in endpoints (run queries and read or upsert graph data). You can also generate snippets from the console with Connect via APIs.

The resource model

Control-plane resources are nested, which makes the endpoints predictable: an organization owns cloud providers and workgroups, a workgroup contains workspaces, and each workspace is attached to a database created with that workspace. Add-ons install at the organization and attach to a workspace.

Authentication

Every request to this API needs an API key in the x-api-key header. If you don’t have a key yet, create an API key in Savanna. Only an organization administrator can create one. If you don’t have that role, reach out to an organization administrator to mint a key with the access you need.

Endpoints

The list below is grouped by task. Each endpoint has its own page with the parameters, payload, and responses for that call.

Choose a cloud provider

TigerGraph-operated providers are the default. Bring Your Own Cloud (BYOC) registers a cloud account you own so workgroups can run there.

List public cloud providers: list the providers TigerGraph operates.
List cloud providers: list the BYOC providers registered to your organization.
Get cloud provider details: return one BYOC provider.
Create a cloud provider: register a cloud account you own with Savanna.
Validate a cloud provider: check whether a BYOC registration would succeed.
Update a cloud provider: rename a BYOC provider or record a version against it.
Upgrade a cloud provider: upgrade Savanna components in a BYOC account.
Delete a cloud provider: unregister a BYOC provider.

Provision graph infrastructure

Create, update, and delete the workgroups and workspaces that host your graphs. A database is created with the workspace; there is no separate create-database call.

Create a workgroup: create a workgroup with a cloud provider, region, and deployment settings.
List workgroups: list the workgroups in your organization.
Get workgroup details: return details for a workgroup.
Update a workgroup: update a workgroup name, application logging, or encryption settings.
Delete a workgroup: delete a workgroup.
Create a workspace: create a workspace in a workgroup. The database is created with it.
Get workspace details: return details for a workspace.
Update a workspace: update a workspace configuration.
Delete a workspace: delete a workspace.
Get database details: return details for a database.
Update a database: rename a database.
Delete a database: delete a database.

Run workspaces on your terms

Control when a workspace is running so it is available when you need it and idle when you don’t.

Resume a workspace: resume a paused workspace.
Pause a workspace: pause a workspace.
Refresh a workspace: refresh a workspace.
Create a workspace schedule: create a recurring workspace schedule.
List workspace schedules: list the schedules for a workspace.
Update a workspace schedule: update a workspace schedule.
Delete a workspace schedule: delete a workspace schedule.

Protect data with backups

Back up a workspace, restore it, and automate backups on a recurring schedule.

List backups: list the backups for a workspace.
Restore a backup: restore a workspace from a backup.
Get backup restore status: return the status of a backup restore job.
Delete a backup: delete the specified workspace backup.
Get backup schedule: return the backup schedule for a workspace.
Set backup schedule: create or replace the backup schedule for a workspace.

A backup schedule automates snapshots of your data. A workspace schedule automates pausing and resuming compute. They are separate features on separate endpoints.

Control who can connect

Restrict network access to a workgroup and manage the database users inside a workspace.

Add an allowed IP: add an IP address or CIDR range to a workgroup allow list.
List allowed IPs: list the IP addresses and CIDR ranges on a workgroup allow list.
Check the current IP: return your current public IP and whether the allow list permits it.
Update an allowed IP: update an entry in a workgroup allow list.
Delete an allowed IP: remove an IP address or CIDR range from a workgroup allow list.
Enable the allow list: enable IP allow-list enforcement for a workgroup.
Disable the allow list: disable IP allow-list enforcement for a workgroup.
Create an in-database user: create an in-database GSQL user for a workspace.
List in-database users: list the in-database GSQL users for a workspace.
Update an in-database user’s password: update an in-database GSQL user’s password.
Delete an in-database user: delete an in-database GSQL user from a workspace.

Enable add-ons

Install GraphStudio, Insights, GraphQL, and other add-ons, then attach them to a workspace.

List available add-ons: list the add-ons available to your organization.
Install an add-on: install an add-on, or enable or disable it.
List installed add-ons: list the add-ons installed for your organization.
Get installed add-on details: return a single installed add-on.
List add-on workspaces: list the workspaces that have a given add-on enabled.
List add-on configurations: list configurations of a given name for an installed add-on.
Create an add-on configuration: create a configuration for an installed add-on.
Update an add-on configuration: update a configuration of an installed add-on.
Delete an add-on configuration: delete a configuration of an installed add-on.

Administer your organization

Discover available capacity and manage the people in your org.

Get supported workspace options: list the regions, TigerGraph versions, and workspace types available to your organization.
List org users: list the users in your organization. This endpoint does not support API key authentication.
Update an org user’s role: update an organization user’s role. This endpoint does not support API key authentication.

Common use cases

Provision on demand: pick a provider with List public cloud providers, stand up a full environment with Create a workgroup and Create a workspace, then tear it down with Delete a workspace.
Control cost automatically: pause idle compute with Pause a workspace and Resume a workspace, or automate it with Create a workspace schedule.
Protect your data: snapshot and recover with Set backup schedule and Restore a backup.
Secure access: restrict traffic with Add an allowed IP and Enable the allow list, and manage logins with Create an in-database user.
CI/CD integration: create ephemeral workspaces for tests or preview environments, polling Get workspace details until the status is ready.

Savanna REST API