--- title: "Savanna REST API" component: "savanna" version: "main" module: "rest-api" html_url: "/savanna/main/rest-api/index.html" --- [View as HTML](/savanna/main/rest-api/index.html) # Savanna REST API 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: ```none 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](https://www.tigergraph.com/docs/tigergraph-server/4.3/api/gsql-endpoints) (schema, loading, and query installation) and the [REST++ built-in endpoints](https://www.tigergraph.com/docs/tigergraph-server/4.3/api/built-in-endpoints) (run queries and read or upsert graph data). You can also generate snippets from the console with [Connect via APIs](../workgroup-workspace/workspaces/connect-via-api.md). ## 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](create-api-key.md) 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](endpoints/list-public-cloud-providers.md): list the providers TigerGraph operates. * [List cloud providers](endpoints/list-cloud-providers.md): list the BYOC providers registered to your organization. * [Get cloud provider details](endpoints/get-cloud-provider-details.md): return one BYOC provider. * [Create a cloud provider](endpoints/create-a-cloud-provider.md): register a cloud account you own with Savanna. * [Validate a cloud provider](endpoints/validate-a-cloud-provider.md): check whether a BYOC registration would succeed. * [Update a cloud provider](endpoints/update-a-cloud-provider.md): rename a BYOC provider or record a version against it. * [Upgrade a cloud provider](endpoints/upgrade-a-cloud-provider.md): upgrade Savanna components in a BYOC account. * [Delete a cloud provider](endpoints/delete-a-cloud-provider.md): 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](endpoints/create-a-workgroup.md): create a workgroup with a cloud provider, region, and deployment settings. * [List workgroups](endpoints/list-workgroups.md): list the workgroups in your organization. * [Get workgroup details](endpoints/get-workgroup-details.md): return details for a workgroup. * [Update a workgroup](endpoints/update-a-workgroup.md): update a workgroup name, application logging, or encryption settings. * [Delete a workgroup](endpoints/delete-a-workgroup.md): delete a workgroup. * [Create a workspace](endpoints/create-a-workspace.md): create a workspace in a workgroup. The database is created with it. * [Get workspace details](endpoints/get-workspace-details.md): return details for a workspace. * [Update a workspace](endpoints/update-a-workspace.md): update a workspace configuration. * [Delete a workspace](endpoints/delete-a-workspace.md): delete a workspace. * [Get database details](endpoints/get-database-details.md): return details for a database. * [Update a database](endpoints/update-a-database.md): rename a database. * [Delete a database](endpoints/delete-a-database.md): 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](endpoints/resume-a-workspace.md): resume a paused workspace. * [Pause a workspace](endpoints/pause-a-workspace.md): pause a workspace. * [Refresh a workspace](endpoints/refresh-a-workspace.md): refresh a workspace. * [Create a workspace schedule](endpoints/create-a-workspace-schedule.md): create a recurring workspace schedule. * [List workspace schedules](endpoints/list-workspace-schedules.md): list the schedules for a workspace. * [Update a workspace schedule](endpoints/update-a-workspace-schedule.md): update a workspace schedule. * [Delete a workspace schedule](endpoints/delete-a-workspace-schedule.md): delete a workspace schedule. ### Protect data with backups Back up a workspace, restore it, and automate backups on a recurring schedule. * [List backups](endpoints/list-backups.md): list the backups for a workspace. * [Restore a backup](endpoints/restore-a-backup.md): restore a workspace from a backup. * [Get backup restore status](endpoints/get-backup-restore-status.md): return the status of a backup restore job. * [Delete a backup](endpoints/delete-a-backup.md): delete the specified workspace backup. * [Get backup schedule](endpoints/get-backup-schedule.md): return the backup schedule for a workspace. * [Set backup schedule](endpoints/set-backup-schedule.md): create or replace the backup schedule for a workspace. > [!NOTE] > 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](endpoints/add-an-allowed-ip.md): add an IP address or CIDR range to a workgroup allow list. * [List allowed IPs](endpoints/list-allowed-ips.md): list the IP addresses and CIDR ranges on a workgroup allow list. * [Check the current IP](endpoints/check-the-current-ip.md): return your current public IP and whether the allow list permits it. * [Update an allowed IP](endpoints/update-an-allowed-ip.md): update an entry in a workgroup allow list. * [Delete an allowed IP](endpoints/delete-an-allowed-ip.md): remove an IP address or CIDR range from a workgroup allow list. * [Enable the allow list](endpoints/enable-the-allow-list.md): enable IP allow-list enforcement for a workgroup. * [Disable the allow list](endpoints/disable-the-allow-list.md): disable IP allow-list enforcement for a workgroup. * [Create an in-database user](endpoints/create-an-in-database-user.md): create an in-database GSQL user for a workspace. * [List in-database users](endpoints/list-in-database-users.md): list the in-database GSQL users for a workspace. * [Update an in-database user's password](endpoints/update-an-in-database-users-password.md): update an in-database GSQL user's password. * [Delete an in-database user](endpoints/delete-an-in-database-user.md): 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](endpoints/list-available-add-ons.md): list the add-ons available to your organization. * [Install an add-on](endpoints/install-an-add-on.md): install an add-on, or enable or disable it. * [List installed add-ons](endpoints/list-installed-add-ons.md): list the add-ons installed for your organization. * [Get installed add-on details](endpoints/get-installed-add-on-details.md): return a single installed add-on. * [List add-on workspaces](endpoints/list-add-on-workspaces.md): list the workspaces that have a given add-on enabled. * [List add-on configurations](endpoints/list-add-on-configurations.md): list configurations of a given name for an installed add-on. * [Create an add-on configuration](endpoints/create-an-add-on-configuration.md): create a configuration for an installed add-on. * [Update an add-on configuration](endpoints/update-an-add-on-configuration.md): update a configuration of an installed add-on. * [Delete an add-on configuration](endpoints/delete-an-add-on-configuration.md): 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](endpoints/get-supported-workspace-options.md): list the regions, TigerGraph versions, and workspace types available to your organization. * [List org users](endpoints/list-org-users.md): list the users in your organization. This endpoint does not support API key authentication. * [Update an org user's role](endpoints/update-an-org-users-role.md): 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](endpoints/list-public-cloud-providers.md), stand up a full environment with [Create a workgroup](endpoints/create-a-workgroup.md) and [Create a workspace](endpoints/create-a-workspace.md), then tear it down with [Delete a workspace](endpoints/delete-a-workspace.md). * **Control cost automatically**: pause idle compute with [Pause a workspace](endpoints/pause-a-workspace.md) and [Resume a workspace](endpoints/resume-a-workspace.md), or automate it with [Create a workspace schedule](endpoints/create-a-workspace-schedule.md). * **Protect your data**: snapshot and recover with [Set backup schedule](endpoints/set-backup-schedule.md) and [Restore a backup](endpoints/restore-a-backup.md). * **Secure access**: restrict traffic with [Add an allowed IP](endpoints/add-an-allowed-ip.md) and [Enable the allow list](endpoints/enable-the-allow-list.md), and manage logins with [Create an in-database user](endpoints/create-an-in-database-user.md). * **CI/CD integration**: create ephemeral workspaces for tests or preview environments, polling [Get workspace details](endpoints/get-workspace-details.md) until the status is ready. ## Related topics * [Create an API key](create-api-key.md). Generate a key in Organization Settings. * [Connect via APIs](../workgroup-workspace/workspaces/connect-via-api.md). Data-plane curl, Python, and JavaScript examples.