Stack-SDK extension-call pattern
When a project enables an extension, the extension can expose a runtime API that the project's application code calls. This page describes how that call is made today and the typed call pattern the platform is designed to offer on top of it.
1. Status
The typed factory described in §3, k9o.extension(slug), is a design target. None of the SDKs ships it yet, and no extension-to-extension call is available either. Application code reaches an installed extension's runtime API over HTTP (§2). The SDKs' own clients (createClient and its per-language equivalents) cover the platform's pillars; they do not expose installed extensions.
Extension authors write their extension against @k9o/extensions-sdk. The package named @k9o/extensions on npm is a placeholder and is not the author SDK.
2. Calling an installed extension today
An installed extension's runtime API is served by the gateway under the project:
<orgSlug>.api.k9o.io/@<projectSlug>/extensions/<slug>/api/<apiSlug>
Any HTTP method the extension declares is accepted. The methods, paths and bodies available under <apiSlug> are the extension's own: they are described by the OpenAPI document the extension bundles in its manifest (surfaces.runtime_api, see the Extensions API reference).
3. Design target: the typed installation-instance pattern
The planned shape is a factory, extension(slug), that returns a typed instance bound to the project's installed-extension context. Its method tree would be generated from the extension's bundled OpenAPI document, so parameter shapes, return types and error variants surface through the language's type system. The design has these properties:
| Property | Behaviour |
|---|---|
| Project-scoped credentials | The instance carries the project's credentials transparently, so each call needs no per-call boilerplate |
| Tier-bound consumption metering | Extension calls compose against the project's billing dimensions, and consumption shows up in the project's billing surface the same way as native API calls |
| Audit attribution | Every extension call is attributed to the extension in the project's audit ledger |
For extensions that ship with the SDK distribution, the typed bindings would be included in the package. For open-ended community extensions, a codegen step run after enabling the extension would produce a local typed module. Inbound webhook handlers would receive a context typed against the extension's declared webhook ingress shape, already verified by the gateway per Security: Webhook signature verification. This page will gain call examples when the SDK methods ship.
4. See also
- Extension typing model: the typing mechanism the design target relies on.
- Extensions API reference: the framework contract extensions install against, including the
surfaces.runtime_apideclaration. - Slug Addressing: the slug identifier scheme extension routes resolve against.
- Webhook signature verification: the gateway-side verification that authenticates inbound webhook payloads.
- Build Your Own Extension: author-facing guide for shipping an extension.