Keboola SKILL.md: Clarify Stack URL Concept

Hello there! Today, we're diving deep into a crucial aspect of working with Keboola that might seem a little obscure at first glance: the Stack URL.

This article is all about making sure you, our fantastic users, have a crystal-clear understanding of what a Stack URL is, why it's different from your Project ID, and how it plays a vital role in your interactions with Keboola, especially when you're dealing with our APIs. We've noticed a bit of confusion stemming from a missing explanation in our SKILL.md documentation, and we're here to clear the air!

Understanding the Keboola Stack URL vs. Project ID

Let's get straight to the heart of the matter. When you're using Keboola, you're working within a specific environment. This environment is often referred to as a stack. Think of it like this: Keboola operates in different geographical regions to ensure optimal performance and data residency. These regions are our stacks. Each stack has its own unique base URL, which is your Stack URL. You might be familiar with the default connection.keboola.com, but did you know there are others?

For instance, if you're based in Europe, you might be using connection.eu-central-1.keboola.com, or if you're in another region, it could be something entirely different. The critical point here is that your Stack URL is the primary address for all your API communications with your specific Keboola environment. It’s the gateway to your data and resources within that particular stack. This is distinct from your Project ID. Your Project ID is a unique identifier for your specific project within a stack. You need both – the Stack URL to know where to send your request, and the Project ID to tell Keboola which project the request pertains to. Imagine sending a letter: the Stack URL is the city and zip code, and the Project ID is the street address and house number. You need both pieces of information for the letter to reach its intended destination correctly.

Why the Distinction Matters for API Authentication

This distinction is absolutely vital when you're setting up API authentication. When you generate an API token, it’s intrinsically linked to a specific project within a specific stack. When you make an API call, you need to authenticate using that token, and crucially, you need to send that request to the correct Stack URL. If you send a request with a token meant for the EU stack to the US stack's URL, it simply won't work. It's like trying to use your US phone number to call a friend in the UK and expecting it to connect seamlessly without specifying the country code. The authentication mechanism will fail because the server at the specified URL doesn't recognize the request in the context of its own environment.

This is precisely why the SKILL.md documentation needs to be clearer. Historically, examples might have hardcoded connection.keboola.com without sufficient emphasis on regional variations. This can lead to significant confusion, especially for users who are not on the default US stack. They might be copying and pasting examples directly, only to find their API calls failing without understanding why. The error messages might be cryptic, leading to frustration and wasted time troubleshooting. We need to ensure that the documentation explicitly guides users on how to identify their correct Stack URL and how it forms the base for all their API interactions. This includes showing how the token, Stack URL, and Project ID work in concert to ensure secure and successful API communication. By understanding this fundamental relationship, you can avoid common pitfalls and ensure your automated workflows and integrations run smoothly. This clarity empowers you to harness the full potential of Keboola's API capabilities, regardless of your geographical location or deployment region.

Navigating Regional Deployments: Finding Your Stack URL

So, how do you find this all-important Stack URL? It’s actually simpler than you might think, and it’s often right under your nose! The easiest way to identify your correct Stack URL is by looking at the URL you use to log into the Keboola UI. Yes, it’s that straightforward!

If you log in using connection.keboola.com, then that’s likely your Stack URL for API calls. However, if your login URL is something like connection.eu-central-1.keboola.com, connection.us-east-1.keboola.com, or any other regional variant, then that is the base URL you should be using for your API requests. Keboola’s design ensures consistency between your UI access point and your API endpoint base. This consistency is a deliberate feature to simplify management and reduce the cognitive load on users. You don't need to go digging through obscure configuration files or contact support; your daily login is the key.

Understanding Different Regional Stacks

Keboola’s global presence means we have multiple regional deployments, or stacks. These stacks are strategically located to provide low latency and comply with data sovereignty regulations. Common examples include:

• US East (N. Virginia): Typically connection.us-east-1.keboola.com (or sometimes just connection.keboola.com as a default).
• EU Central (Frankfurt): Typically connection.eu-central-1.keboola.com.
• Other regions: As Keboola expands, more regional stack URLs may become available.

The ability to deploy in different regions is a significant advantage for businesses that need to keep their data within specific geographical boundaries due to compliance requirements like GDPR. By understanding your specific regional stack, you ensure that your data processing activities adhere to these regulations. It also means that API calls are routed to the closest server, minimizing network latency and improving the overall performance of your data pipelines and applications interacting with Keboola.

The Role of Stack URL in API Usage Patterns

When you are building integrations or scripts that interact with the Keboola API, the Stack URL serves as the base URL for all your requests. Every API endpoint – whether you're fetching data about your projects, triggering a specific job, or uploading a file – will be appended to this base URL. For example, if you want to list all configurations for a project, and your Stack URL is connection.eu-central-1.keboola.com and your Project ID is 12345, your API call might look something like this:

curl -X GET https://connection.eu-central-1.keboola.com/v2/storage/tables \
     -H "X-StorageApi-Token: YOUR_API_TOKEN"

Notice how https://connection.eu-central-1.keboola.com is the foundation. If you were to use https://connection.keboola.com instead, and your project actually resides in the EU stack, the request would likely fail with an error indicating a resource not found or an authentication issue, because the connection.keboola.com server wouldn't know about your project in the EU region.

This understanding is crucial for troubleshooting. If your API calls are suddenly failing, or if they never worked in the first place, the first thing to check is whether you are using the correct Stack URL. Is it the one that matches your UI login? Have you hardcoded a default URL that doesn't apply to your specific deployment? The documentation needs to provide clear examples that illustrate this, perhaps showing side-by-side comparisons of how a request would be structured for different regional stacks. This practical guidance will demystify API interactions and empower users to build robust and reliable integrations with Keboola.

Fixing Documentation Gaps for a Smoother User Experience

We've identified that the SKILL.md documentation needs a significant update to address the confusion around Stack URLs. The current state, where connection.keboola.com is often hardcoded without proper explanation, poses a real challenge for users, especially those operating outside the default US region. This needs to be rectified to ensure a seamless and intuitive user experience.

What's Missing and Why It Matters

Currently, the documentation lacks several key pieces of information:

1. No Explanation of Multiple Regional Stacks: Users aren't explicitly told that Keboola operates across different geographical regions. This fundamental piece of information is the root of much confusion.
2. No List of Possible Stack URLs: Providing a list of common regional stack URLs (like connection.eu-central-1.keboola.com, connection.us-east-1.keboola.com, etc.) would give users concrete examples and a reference point.
3. No Guidance on How to Find Your Stack URL: As mentioned earlier, directing users to check their UI login URL is the simplest method, but this isn't clearly communicated.
4. No Explanation of Stack URL Independence from Project ID: The documentation needs to hammer home that the Stack URL is the location, and the Project ID is the identifier within that location. They are separate but complementary pieces of information.
5. Potential Confusion for Non-US Users: Hardcoding connection.keboola.com can lead EU or other regional users to mistakenly use a URL that doesn't serve their data, resulting in failed operations.

The Impact of These Gaps

The consequences of these documentation shortcomings are tangible:

• Difficulty Determining Correct Base URL: Users struggle to figure out which specific URL to use as the base for their API calls, leading to guesswork and errors.
• Incorrect Regional Usage: Users might inadvertently try to access resources on the wrong regional stack, causing authentication failures and data access problems.
• Confusion Between UI and API Endpoints: A lack of clarity can blur the lines between the user interface URLs and the API endpoint structures, leading to misunderstandings.
• Lack of Troubleshooting Guidance: When issues arise, users lack the foundational knowledge about Stack URLs to effectively troubleshoot