GraphQL API

In this article we disclose the full GraphQL schema used by the web app GUI. A smaller subset of this API is also used by the Terraform provider. Both can be accessed at the /graphql endpoint of your account using POST HTTP method.

Authenticating with the API

In order to use the API, you will need a bearer token. There are two ways of obtaining these. The easy way is to log in to the right Spacelift account and retrieve the token from local storage:

The other option is to use a personal GitHub token and exchange it for Spacelift's one:

mutation GetSpaceliftToken($token: String!) {
oauthUser(token: $token) {
jwt
}
}

We suggest using a purpose-built GraphQL client to maintain your sanity. For example, we had great success with Insomnia REST Client.

If you want to access the API reliably in an automated way, we suggest using the second approach since Spacelift tokens expire after an hour.

GraphQL schema(s)

User-facing schema
Provider schema
User-facing schema
schema {
query: Query
mutation: Mutation
}
type Query {
# Details of a single Context.
context(id: ID!): Context
# List of all the contexts in the account.
contexts: [Context!]!
# Name of the account.
name: String
# List of GitHub repositories in the account.
repositories: [Repository!]!
# Details of a single Stack.
stack(id: ID!): Stack
# List of all the stacks in the account.
stacks: [Stack!]!
# List of GitHub teams in the account.
teams: [Team!]!
# Type of the GitHub account.
type: AccountType
# Usage for the last 30 days.
usage: Usage!
# Current user, if any.
viewer: User
}
type Mutation {
# Create a new context.
contextCreate(name: String!, description: String): Context!
# Delete an existing context.
contextDelete(id: ID!): Context
# Update an existing context.
contextUpdate(id: ID!, name: String!, description: String): Context!
# Attach context to a Stack.
contextAttach(id: ID!, stack: ID!, priority: Int!): ContextStackAttachment!
# Detach context from a a Stack.
contextDetach(id: ID!): ContextStackAttachment
# Add a context config element.
contextConfigAdd(context: ID!, config: ConfigInput!): ConfigElement!
# Delete a context config element.
contextConfigDelete(context: ID!, id: ID!): ConfigElement
# Get a GitHub URL to redirect to.
oauthRedirect: OAuthRedirect!
# Refresh the Spacelift user by querying against the GitHub API.
oauthRefresh: User!
# Exchange code and temporary token for a GitHub token.
oauthToken(code: String!, state: String!, temporaryToken: String!): String!
# Exchange GitHub token for a Spacelift User.
oauthUser(token: String!): User!
# Cancel a Run that has not yet started.
runCancel(stack: ID!, run: ID!): Run!
# Confirm a Run that's waiting to be applied.
runConfirm(stack: ID!, run: ID!): Run!
# Discard a Run that's waiting to be applied.
runDiscard(stack: ID!, run: ID!): Run!
# Retry a PR Run that has finished.
runRetry(stack: ID!, run: ID!, refreshState: Boolean): Run!
# Stop a Run that's currently in progress.
runStop(stack: ID!, run: ID!): Run!
# Trigger a Run against the current HEAD.
runTrigger(stack: ID!): Run!
# Create a new stack. The third argument (stackObjectID) is optional, and
# should only be used when creating a Stack with pre-existing state that is
# handed over to Spacelift for further management.
stackCreate(input: StackInput!, manageState: Boolean!, stackObjectID: String): Stack!
# Delete an existing stack.
stackDelete(id: ID!): Stack
# Set stack AWS role delegation. Setting an empty ARN removes delegation.
stackSetAwsRoleDelegation(id: ID!, roleArn: String): Stack
# Update an existing stack.
stackUpdate(id: ID!, input: StackInput!): Stack!
# Add a stack config element.
stackConfigAdd(stack: ID!, config: ConfigInput!): ConfigElement!
# Delete a stack config element.
stackConfigDelete(stack: ID!, id: ID!): ConfigElement!
# Lock the stack for exclusive use.
stackLock(id: ID!): Stack!
# Unlock the stack.
stackUnlock(id: ID!): Stack!
# Generate pre-signed state upload URL.
stateUploadUrl: StateUploadUrl!
# Create a Task from a command.
taskCreate(stack: ID!, command: String!): Run!
}
# Commit represents a GitHub commit.
type Commit {
# GitHub username of the Commit author (optional).
authorLogin: String
# Name of the Commit author (required).
authorName: String!
# URL of the commit author avatar.
avatarURL: String!
# Git commit SHA.
hash: String!
# Short message associated with the commit (only the first line!);
message: String!
# Unix timestamp of the commit.
timestamp: Int!
# Full URL linking to the commit in GitHub.
url: String!
}
# ConfigElement is a stack runtime configuration element: environment variable
# or file mount.
type ConfigElement {
# Environment variable name or file mount relative path.
id: ID!
# SHA256 checksum of the value.
checksum: String!
# Whether the config element is only known at runtime.
runtime: Boolean!
# Config element type.
type: ConfigType!
# Environment variable value, only exposed if the variable is not
# marked as write-only.
value: String
# When a variable is marked as write-only, its value is only accessible
# to the Run, but not in the API or the UI.
writeOnly: Boolean!
}
type ConfigElementWithSource {
# Optional context if the element is coming from a context.
context: StackContextAttachment
# Wrapped config element.
element: ConfigElement!
}
type Context {
# Unique (within a single organization), immutable name of the context.
id: ID!
# Single stack attachment for this Context.
attachedStack(id: ID!): ContextStackAttachment
# List of stacks attached to this Context.
attachedStacks: [ContextStackAttachment!]!
# Single context config element.
configElement(id: ID!): ConfigElement
# Full list of stack config elements.
config: [ConfigElement!]!
# Free-form context description for the users, supports Markdown.
description: String
# Fancy, mutable name of the Context to show in the UI.
name: String!
}
# ContextStackAttachment is the stack attachment viewed from the Context.
type ContextStackAttachment {
# Globally unique attachment identifier.
id: ID!
# Slug of the attached stack.
stackId: ID!
# Name of the attached stack.
stackName: String!
# Context in question.
priority: Int!
}
# Delta is the number of resources affected by a Run in various ways.
type Delta {
# Count of resources to create.
addCount: Int
# Names of resources to create.
addResources: [String!]!
# Count of resources to modify in-place.
changeCount: Int
# Names of resources to modify in-place.
changeResources: [String!]!
# Count of resources to destroy.
deleteCount: Int
# Names of resources to destroy.
deleteResources: [String!]!
# Total number of resources in the state before applying the change.
resources: Int!
}
# LogMessage represents a single log line.
type LogMessage {
# Actual message.
message: String!
# Unix timestamp representing log line creation.
timestamp: Int!
}
# LogsResponse is a response to a query for a batch of logs.
type LogsResponse {
# Whether the log stream even exists.
exists: Boolean!
# Is the log stream finished.
finished: Boolean!
# Is more messages available.
hasMore: Boolean!
# List of messages.
messages: [LogMessage!]!
# Token used to retrieve the next batch of log messages.
nextToken: String
}
# OAuthRedirect is a response to an OAuth redirect query.
type OAuthRedirect {
# Full URL to the identity provider (GitHub).
providerUrl: String!
# Temporary token to be persisted in the browser.
temporaryToken: String!
}
# GitHub repository with branches.
type Repository {
# Name of the repository.
id: ID!
# List of up to last 20 branches, sorted by most recent commit timestamp.
branches: [String!]!
}
# Run represents the main concept in Spacelift.
type Run {
# Globally unique ID (ULID) of the Run.
id: ID!
# Name of the branch for which this Run has been created.
branch: String!
# Command - only useful for Tasks.
command: String
# Commit prepresenting the HEAD of the branch at the time of triggering
# the Run.
commit: Commit!
# Unix timestamp representing Run creation.
createdAt: Int!
# Change in resources tracked by the Stack's state that will be caused
# by this Run.
delta: Delta
# Convenience helper, allowing a quick check on whether the Run has finished.
finished: Boolean!
# Run history as a list of state transitions.
history: [RunStateTransition!]!
# Paginated slice of Run logs associated with one of the current Run's
# (past or present) states.
logs(state: RunState!, token: String): LogsResponse
# Indicates whether the Terraform state should be refreshed.
refreshState: Boolean!
# Individual runtime configuration for this Run.
runtimeConfig: RuntimeConfig
# Current state of the Run.
state: RunState!
# Title of the Run for UI consumption.
title: String!
# The user who manually triggered this Run, if any.
triggeredBy: String
# Type of the Run.
type: RunType!
# Unix timestamp of the last update.
updatedAt: Int!
}
# RuntimeConfig is the runtime configuration pulled from GitHub for each
# Run separately.
type RuntimeConfig {
# Indicates where the root of the Terraform project is.
projectRoot: String!
# Name of the Docker image used to process the Run.
runnerImage: String!
# Terraform version used to process the Run.
terraformVersion: String!
}
# Change in the Run state, along with its metadata.
type RunStateTransition {
# Indicates whether the state transition has logs.
hasLogs: Boolean!
# Optional note about the state transition.
note: String
# New state of the Run.
state: RunState!
# Whether the transition finishes the run.
terminal: Boolean!
# Unix timestamp of the Run.
timestamp: Int!
# Unix timestamp of the subsequent state transition, if any.
until: Int
# GitHub username of the individual who caused the change, if any.
username: String
}
# Stack represents a single Spacelift project.
type Stack {
# Unique (within a single organization), immutable name of the stack.
id: ID!
# Administrative stacks can manage other Stacks at runtime.
administrative: Boolean!
# List of contexts attached to this Stack.
attachedContexts: [StackContextAttachment!]!
# AWS IAM role to assume, if any.
awsAssumedRoleARN: String
# AWS IAM assume role creation link.
awsAssumeRoleLink: String!
# AWS IAM assume role policy statement.
awsAssumeRolePolicyStatement: String!
# The Run that's currently holding the stack lock, if any.
blocker: Run
# Git branch of the repo that the Stack is tracking.
branch: String!
# Whether the user has write privileges for this Stack.
canWrite: Boolean!
# Single stack config element.
configElement(id: ID!): ConfigElement
# Full list of stack config elements.
config: [ConfigElement!]!
# Free-form stack description for the users, supports Markdown.
description: String
# Username of the person who locked the Stack for their exclusive use.
lockedBy: String
# Is Spacelift responsible for managing the Terraform state file.
managesStateFile: Boolean!
# Fancy, mutable name of the Stack to show in the UI.
name: String!
# Readers team, if any.
readers: Team
# GitHub repository tracked by this stack, as account/repo.
repository: String!
# Individual Run (or task) by ID.
run(id: ID!): Run
# Paginated list of Runs targeting the tracked branch.
runs(before: ID): [Run!]!
# Calculated runtime config containing elements coming from contexts,
# stack and various integrations.
runtimeConfig: [ConfigElementWithSource!]!
# Current state of the Stack.
state: StackState!
# Paginated list of Tasks.
tasks(before: ID): [Run!]!
# Terraform version set by the admin or last used to apply changes.
terraformVersion: String
# Writers team, if any.
writers: Team
}
# StackContextAttachment is the stack attachment viewed from the Stack.
type StackContextAttachment {
# Globally unique attachment identifier.
id: ID!
# Full list of stack config elements.
config: [ConfigElement!]!
# ID of the attached context.
contextId: ID!
# Name of the attached context.
contextName: String!
# Context in question.
priority: Int!
}
# StateUploadUrl represents a pre-signed URL that can be used to upload an
# existing state file.
type StateUploadUrl {
# Temporary object ID to be passed when creating the Stack.
objectId: String!
# Pre-signed URL to use to upload the file.
url: String!
}
# GitHub authorized Team.
type Team {
# Opaque GitHub team ID.
id: ID!
# Human-friendly name of the GitHub team.
name: String!
# URL-friendly name of the GitHub team.
slug: String!
}
type Usage {
# Number of minutes that can be used within any 30 days period.
allowedMinutes: Int!
# Number of users who can log in for any 30 days.
allowedSeats: Int!
# Logins of users who logged in to any of the stack
logins: [UserLogin!]!
# Number of minutes used within the last 30 days.
usedMinutes: Int!
# Number of users who last logged in to any of the stacks for the last
# 30 days.
usedSeats: Int!
}
# UserLogin represents the last login attempt for a single GitHub user.
type UserLogin {
# GitHub username of the user.
username: String!
# Last login timestamp.
timestamp: Int!
}
# Spacelift user.
type User {
# GitHub username.
id: ID!
# Whether the user has org-wide admin privileges.
admin: Boolean!
# URL of the user avatar.
avatarURL: String!
# Temporary access token as a string.
jwt: String!
# Full name of the GitHub user.
name: String!
# Unix timestamp of token validity expiration.
validUntil: Int!
}
enum AccountType {
UNKNOWN
USER
ORG
}
enum ConfigType {
ENVIRONMENT_VARIABLE
FILE_MOUNT
}
# RunState represents a discrete state of a Run.
enum RunState {
UNKNOWN
QUEUED
CANCELED
INITIALIZING
PLANNING
FAILED
FINISHED
UNCONFIRMED
DISCARDED
CONFIRMED
APPLYING
PERFORMING
PERFORMED
STOPPED
}
# RunType is a type of the Run.
enum RunType {
UNKNOWN
PROPOSED
TRACKED
TASK
}
# StackState represents a discrete state of a Stack, which is also the state of
# its most currently running Run.
enum StackState {
NONE
INITIALIZING
PLANNING
FAILED
FINISHED
UNCONFIRMED
DISCARDED
CONFIRMED
APPLYING
STOPPED
}
# Arguments used to create and update an individual Stack.
input StackInput {
# Administrative stacks can manage other Stacks at runtime.
administrative: Boolean!
# Name of the branch to track.
branch: String!
# Optional free-form description of the Stack.
description: String
# Human-friendly, mutable stack name.
name: String!
# Optional readers team slug.
readersSlug: String
# Name of the repository to track.
repository: String!
# Terraform version to use.
terraformVersion: String
# Optional writers team slug.
writersSlug: String
}
input ConfigInput {
id: ID!
type: ConfigType!
value: String!
writeOnly: Boolean!
}
Provider schema
schema {
query: Query
mutation: Mutation
}
type Query {
# Details of a single Context.
context(id: ID!): Context
# Name of the account.
name: String
# Details of a single Stack.
stack(id: ID!): Stack
# Type of the GitHub account.
type: AccountType
}
type Mutation {
# Create a new context.
contextCreate(name: String!, description: String): Context!
# Delete an existing context.
contextDelete(id: ID!): Context
# Update an existing context.
contextUpdate(id: ID!, name: String!, description: String): Context!
# Attach context to a Stack.
contextAttach(id: ID!, stack: ID!, priority: Int!): ContextStackAttachment!
# Detach context from a a Stack.
contextDetach(id: ID!): ContextStackAttachment
# Add a context config element.
contextConfigAdd(context: ID!, config: ConfigInput!): ConfigElement!
# Delete a context config element.
contextConfigDelete(context: ID!, id: ID!): ConfigElement
# Create a new stack. The third argument (stackObjectID) is optional, and
# should only be used when creating a Stack with pre-existing state that is
# handed over to Spacelift for further management.
stackCreate(input: StackInput!, manageState: Boolean!, stackObjectID: String): Stack!
# Delete an existing stack.
stackDelete(id: ID!): Stack
# Set stack AWS role delegation. Setting an empty ARN removes delegation.
stackSetAwsRoleDelegation(id: ID!, roleArn: String): Stack
# Update an existing stack.
stackUpdate(id: ID!, input: StackInput!): Stack!
# Add a stack config element.
stackConfigAdd(stack: ID!, config: ConfigInput!): ConfigElement!
# Delete a stack config element.
stackConfigDelete(stack: ID!, id: ID!): ConfigElement!
# Generate pre-signed state upload URL.
stateUploadUrl: StateUploadUrl!
}
# ConfigElement is a stack runtime configuration element: environment variable
# or file mount.
type ConfigElement {
# Environment variable name or file mount relative path.
id: ID!
# SHA256 checksum of the value.
checksum: String!
# Whether the config element is only known at runtime.
runtime: Boolean!
# Config element type.
type: ConfigType!
# Environment variable value, only exposed if the variable is not
# marked as write-only.
value: String
# When a variable is marked as write-only, its value is only accessible
# to the Run, but not in the API or the UI.
writeOnly: Boolean!
}
type Context {
# Unique (within a single organization), immutable name of the context.
id: ID!
# Single stack attachment for this Context.
attachedStack(id: ID!): ContextStackAttachment
# List of stacks attached to this Context.
attachedStacks: [ContextStackAttachment!]!
# Single context config element.
configElement(id: ID!): ConfigElement
# Full list of stack config elements.
config: [ConfigElement!]!
# Free-form context description for the users, supports Markdown.
description: String
# Fancy, mutable name of the Context to show in the UI.
name: String!
}
# ContextStackAttachment is the stack attachment viewed from the Context.
type ContextStackAttachment {
# Globally unique attachment identifier.
id: ID!
# Slug of the attached stack.
stackId: ID!
# Name of the attached stack.
stackName: String!
# Context in question.
priority: Int!
}
# Stack represents a single Spacelift project.
type Stack {
# Unique (within a single organization), immutable name of the stack.
id: ID!
# Administrative stacks can manage other Stacks at runtime.
administrative: Boolean!
# AWS IAM role to assume, if any.
awsAssumedRoleARN: String
# AWS IAM assume role policy statement.
awsAssumeRolePolicyStatement: String!
# Git branch of the repo that the Stack is tracking.
branch: String!
# Single stack config element.
configElement(id: ID!): ConfigElement
# Full list of stack config elements.
config: [ConfigElement!]!
# Free-form stack description for the users, supports Markdown.
description: String
# Is Spacelift responsible for managing the Terraform state file.
managesStateFile: Boolean!
# Fancy, mutable name of the Stack to show in the UI.
name: String!
# Readers team, if any.
readers: Team
# GitHub repository tracked by this stack, as account/repo.
repository: String!
# Terraform version set by the admin or last used to apply changes.
terraformVersion: String
# Writers team, if any.
writers: Team
}
# StateUploadUrl represents a pre-signed URL that can be used to upload an
# existing state file.
type StateUploadUrl {
# Temporary object ID to be passed when creating the Stack.
objectId: String!
# Pre-signed URL to use to upload the file.
url: String!
}
# GitHub authorized Team.
type Team {
# Opaque GitHub team ID.
id: ID!
# Human-friendly name of the GitHub team.
name: String!
# URL-friendly name of the GitHub team.
slug: String!
}
enum AccountType {
UNKNOWN
USER
ORG
}
enum ConfigType {
ENVIRONMENT_VARIABLE
FILE_MOUNT
}
# Arguments used to create and update an individual Stack.
input StackInput {
# Administrative stacks can manage other Stacks at runtime.
administrative: Boolean!
# Name of the branch to track.
branch: String!
# Optional free-form description of the Stack.
description: String
# Human-friendly, mutable stack name.
name: String!
# Optional readers team slug.
readersSlug: String
# Name of the repository to track.
repository: String!
# Terraform version to use.
terraformVersion: String
# Optional writers team slug.
writersSlug: String
}
input ConfigInput {
id: ID!
type: ConfigType!
value: String!
writeOnly: Boolean!
}