From dc4b3a1f1e4aeed257321ccca7a89934be7af6d1 Mon Sep 17 00:00:00 2001
From: Jiri Semmler <jirka.semmler@gmail.com>
Date: Wed, 15 Jul 2026 11:22:59 +0200
Subject: [PATCH] docs(api): document the machine-readable /apis.json index

Add a "Machine-Readable API Index" section to the Our APIs page,
between the API Documentation Portals and Service Endpoints sections.
Each stack's portal publishes a machine-readable index of its APIs at
https://api.<stack>/apis.json (services with apiUrl + openApiSpecUrl),
intended for agentic usage and tooling.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 overview/api/index.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/overview/api/index.md b/overview/api/index.md
index 0add7a9e..4c301540 100644
--- a/overview/api/index.md
+++ b/overview/api/index.md
@@ -72,6 +72,32 @@ for your own stack — tokens are not valid across stacks, and using the wrong p
 | EU Frankfurt GCP | [api.europe-west3.gcp.keboola.com](https://api.europe-west3.gcp.keboola.com/) |
 | US Virginia GCP | [api.us-east4.gcp.keboola.com](https://api.us-east4.gcp.keboola.com/) |
 
+### Machine-Readable API Index
+
+For agentic usage and tooling (AI agents, MCP servers, CI), each stack's API portal also publishes a
+machine-readable index of its APIs at `https://api.<stack>/apis.json` — for example,
+[api.keboola.com/apis.json](https://api.keboola.com/apis.json). The index lists each available service with
+its base `apiUrl` and a link to its OpenAPI specification (`openApiSpecUrl`), so tools can discover and load
+the specs programmatically:
+
+{% highlight json %}
+{
+  "stack": "keboola.com",
+  "services": [
+    {
+      "id": "storage",
+      "name": "Storage API",
+      "apiUrl": "https://connection.keboola.com",
+      "openApiSpecUrl": "https://api.keboola.com/specs/storage.json"
+    }
+  ]
+}
+{% endhighlight %}
+
+The index is stack-specific (excluded services are omitted). The raw specs under `/specs/` keep their original
+`servers`, so consumers should use the `apiUrl` from the index as the base URL. The `openApiSpecUrl` extension
+mirrors the source document (`.json` or `.yaml`) — use the exact URL from the index rather than assuming one.
+
 ### Service Endpoints
 
 If you are calling the APIs directly (not through the portal), modify the hostname accordingly.