Skip to main content
Version: v2.x

Hasura Cloud API Reference

Introduction

Hasura Cloud provides a GraphQL API to interact with services to create and manage your Cloud Projects using any GraphQL client.

Endpoint

The Hasura Cloud API endpoint is https://data.pro.hasura.io/v1/graphql.

Authentication

Authentication is done using a Personal Access Token that you can create from the Hasura Cloud Dashboard. You can find this option in the "My Account" section on bottom left.

Create a Hasura Cloud personal access token

Once you have created the token it should be used as a header in your requests in the format: Authorization: pat <token>.

Note

This token can be used to authenticate against all of your Hasura Cloud APIs and Projects. It is only revealed once on creation. Make sure you keep it secure. The token will be valid until you delete it from the dashboard.

APIs

Each Hasura Cloud Project is backed by an API entity called "Tenant", with a distinct "Tenant ID" which is different from the "Project ID". Each Project is associated with a Tenant. In some cases, like with the Metrics API, the Project ID is used instead of Tenant ID.

Create a Project

mutation createProject {
createTenant(
cloud: "aws"
region: "us-east-2"
envs: [{ key: "HASURA_GRAPHQL_CORS_DOMAIN", value: "*" }, { key: "MY_ENV_VAR_1", value: "my value 1" }]
) {
id
name
}
}

Get Project Tenant id

query getProjectTenantId {
projects_by_pk(id: "7a79cf94-0e53-4520-a560-1b02bf522f08") {
id
tenant {
id
}
}
}

Get Tenant details

query getTenantDetails {
tenant_by_pk(id: "7a79cf94-0e53-4520-a560-1b02bf522f08") {
id
slug
project {
id
endpoint
}
}
}

Delete a Tenant

mutation deleteTenant {
deleteTenant(tenantId: "7a79cf94-0e53-4520-a560-1b02bf522f08") {
status
}
}

Get ENV Vars

query getTenantENV {
getTenantEnv(tenantId: "7a79cf94-0e53-4520-a560-1b02bf522f08") {
hash
envVars
}
}

Update ENV Vars

mutation updateTenantEnv {
updateTenantEnv(
tenantId: "7a79cf94-0e53-4520-a560-1b02bf522f08"
currentHash: "6902a395d70072fbf8d36288f0eacc36c9d82e68"
envs: [
{ key: "HASURA_GRAPHQL_ENABLE_CONSOLE", value: "true" }
{ key: "ACTIONS_ENDPOINT", value: "https://my-actions-endpoint.com/actions" }
]
) {
hash
envVars
}
}

Create GitHub Preview App

Schedules the creation of a Hasura Cloud Project with Migrations and Metadata from a branch of a GitHub repo.

mutation createGitHubPreviewApp {
createGitHubPreviewApp(
payload: {
githubPersonalAccessToken: "<github_access_token>"
githubRepoDetails: { branch: "main", owner: "my-org", repo: "my-repo", directory: "backend/hasura" }
projectOptions: {
cloud: "aws"
region: "us-east-2"
plan: "cloud_free"
name: "my-app_name"
envVars: [
{ key: "HASURA_GRAPHQL_AUTH_HOOK", value: "https://my-webhook.com" }
{ key: "MY_ENV_VAR_1", value: "my value 1" }
]
}
}
) {
githubPreviewAppJobID
}
}

Input arguments

ArgumentDescription
githubPersonalAccessTokenGitHub personal access token for Hasura Cloud to access the Migrations and Metadata from your repository. Refer to GitHub docs on how to create a GitHub personal access token. The token should have read access to the repository.
under githubRepoDetails: ownerGitHub repository owner (user or organisation)
under githubRepoDetails: repoGitHub repository name.
under githubRepoDetails: branchName of the branch from which to create a Preview App.
under githubRepoDetails: directoryPath to the Hasura Project directory (typically created by the Hasura CLI) containing Migrations and Metadata. The path should be relative to the project's root directory.
under projectOptions: nameName of the Preview App. A Hasura Cloud project will be created with the same name. Can contain lowercase characters, numbers and hyphens.
under projectOptions: cloudThe cloud provider to deploy the Preview App on. A Hasura Cloud project will be created in the specified cloud provider. Available: aws and gcp.
under projectOptions: regionThe region within the cloud provider to deploy the Preview App on. A Hasura Cloud project will be created in the specified region. Refer to the Hasura Cloud dashboard for available options.
under projectOptions: planPricing tier of the created Preview App. Available options: cloud_free and cloud_payg (corresponds to Free Tier and Standard Tier respectively).
under projectOptions: envVarsENV vars to be set for the created Preview App.

Output Fields

ArgumentDescription
githubPreviewAppJobIDJob ID of the Preview App creation job. This does not mean the Preview App is created, the ID identifies the job responsible for creating the Preview App. For the status of the Preview App creation, query the getPreviewAppCreationStatus API.

Fetch Preview App Creation Status

Preview App creation is a multistep process. This query fetches the status of the Preview App creation. The input jobID is the same ID obtained in the output of the Create GitHub Preview App mutation.

query getPreviewAppCreationStatus($jobId: uuid!) {
jobs_by_pk(id: $jobId) {
id
status
tasks {
id
name
task_events {
id
event_type
public_event_data
error
}
}
}
}

Input Arguments

ArgumentDescription
idJob ID of the Preview App creation job. The ID identifies the job responsible for creating the Preview app. This can be obtained from the output of the createGitHubPreviewApp API.