Make the API easier / friendlier to use
GraphQL is a new skill for REST developers. This post is not about GQL. I think GQL is great. This feedback is about everything Spacelift do to make the Developer Experience 10x worse than it could be.
When the Spacelift API is difficult to use, it discourages growth of an ecosystem around the API. There are no utilities or apps of note using the Spacelift API and I believe part of the reason is that the API is so difficult to use.
1. The documentation is sparse writing + looms
cosmetically, the page is a nightmare. Many images are poorly sized and it’s hard to keep track of where you are in the header hierarchy.
Understanding how to authenticate is fundamental, and yet it is poorly documented. The key idea is “Add a header Authorization: bearer $YOUR_JWT but you won’f find this written on the page anywhere! (If you look closely, it’s in a code snippet) Instead we document five ways to get a JWT. One of which is specific to Github Actions. Two of which are only relevant for personal testing (spacectl & PAT).
The docs and UX for getting a static API key suck. You’re forced to download a file containing the secret rather than copy to clipboard. The file contains two secrets and it’s not clear how they differ. The file also doesn’t contain the key ID, which is required during authentication. You have to go back a step, find your new key in the web UI, and copy the ID manually.
Docs for graphiql are simply wrong and do not explain how to authenticate (which is required to access schema).
2. No schema is published, adding a hoop to codegen users (figuring out how to authenticate without having the schema)
I spent 30mins trying to do this and eventually figured out the magical incantation:
npx get-graphql-schema https://demo.app.spacelift.io/graphql > schema.graphql
I still have no idea how to download the schema from our own account subdomain, despite Spacelift staff insisting that using the wrong schema will lead to ruin.
Major companies like Github and Shopify run graphql APIs, and they can publish easily accessible URLs to download their schema. There’s no reason Spacelift cannot do the same.
3 There are only two sources of existing code to learn from. spacectl and
https://github.com/spacelift-io/spacelift-api-examples which both have no “client sdk” layer and rely on non-reusable gql queries plus untyped JSON unmarshalling
Please make API development better.
Log in to comment and vote
Comments4
Tomato Fidget
Sep 15, 2025
I second this feature request. I’ve tried to do a quite simple script - take failed drift checks and make Jira issues for fixing them (we get MS Teams messages).
I’ve failed at not getting the data I want (stacks with failed drift check within last 24 hours) but at getting any data at all.
I don’t have much experience with GraphQL. I’ve tried tooling for introspection, LLMs, and to be honest I have no clue how to proceed with that or what to try next (except for asking Spacelift for support). I understand that it is a technology that I’m simply not familliar with, but entry level seems quite high (lack of examples even) and there isn’t really an alternative (i.e. simplified REST).
That was an afternoon idea to make my team life a bit easier, but with the amount of time and effort it requires at the moment I will have to wait with it for better times.
Violet Highlighter
Jun 20, 2025
Thanks Marcin.
Here’s the problem I’m building a solution for:
Developers want to create an temporary testing environment based on AWS Elastic Beanstalk. When they create this environment, their current code should be deployed here
Once their environment exists, future pushes of code to their test branch should auto-deploy to the environment
The code to create an environment is in our
infrarepo. The application code is inapprepo.My solution requires a system which talks to Spacelift and CircleCI, and has a web UI for developer to CRUD environments.
Here are some example tasks:
When a new environment is created, we should trigger an app build in CircleCI, poll for completion, then trigger a blueprint in Spacelift and poll for completion
It took me a couple of hours to fully write & debug the CCI script
The spacelift script is ongoing
When developer pushes new code, we should build new app code bundle in CircleCI and then notify Spacelift to deploy it
re: MCP Server. Spacelift AI features are still in legal review limbo. I hope to try them soon.
I can live without an SDK. I would require an SDK for features like pagination and rate limit auto-retry, because I don’t want to build that stuff myself. I would really like an SDK for type-safe use of the codebase, which is nearly impossible even with graphql codegen. But my uses are simple enough and I’ve learnt enough in the past month I can live without it.
Natalia Gazda
Jun 17, 2025
Hey Alex! Following up on this - we've actually built something that might interest you. We added GraphQL introspection capabilities to spacectl that work with coding assistants (MCP server). It handles schema discovery, auth examples, and can generate typed clients.
But I'm still curious about your original use case. You mentioned the ecosystem lacks utilities/apps using our API. What were you trying to build when you hit these friction points? Was it:
Also, regarding the specific pain points you raised (auth header docs, API key UX, schema URL) - if we just fixed those basics, would that unblock you? Or is the lack of a proper SDK the real blocker?
The MCP approach helps with AI-assisted development, but I want to make sure we're solving the right problem for developers like you.
Black Breeze
May 27, 2025