Skip to content

Latest commit

 

History

History
217 lines (176 loc) · 10.7 KB

cloud-api-reference.mdx

File metadata and controls

217 lines (176 loc) · 10.7 KB
Raw
description keywords sidebar_position sidebar_label sidebar_class_name
Hasura Cloud API reference
hasura
cloud
docs
API
API reference
14
Hasura Cloud API reference
cloud-icon

import TOCInline from '@theme/TOCInline'; import Thumbnail from '@site/src/components/Thumbnail';

Hasura Cloud API Reference

Available on: Cloud

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.

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

:::info 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.

<TOCInline toc={toc} filterTOC={'apis'} />

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 {#api-ref-create-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

Argument Description
githubPersonalAccessToken GitHub 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: owner GitHub repository owner (user or organisation)
under githubRepoDetails: repo GitHub repository name.
under githubRepoDetails: branch Name of the branch from which to create a Preview App.
under githubRepoDetails: directory Path 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: name Name of the Preview App. A Hasura Cloud project will be created with the same name. Can contain lowercase characters, numbers and hyphens.
under projectOptions: cloud The 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: region The 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: plan Pricing tier of the created Preview App. Available options: cloud_free and cloud_payg (corresponds to Free Tier and Standard Tier respectively).
under projectOptions: envVars ENV vars to be set for the created Preview App.

Output Fields

Argument Description
githubPreviewAppJobID Job 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 {#api-ref-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

Argument Description
id Job 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.