> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/sdks/api-client.md).

# Integrate a generated API client

The SDK is generated from the OpenAPI contract stored with a published API version. Draft, retired, expired, missing-contract, and cross-tenant versions cannot be exported.

## End-to-end flow

1. A platform team publishes an API and immutable version in Developer Portal.
2. The API consumer registers an application and receives the required credential.
3. A platform administrator selects a language and exports the generated SDK ZIP.
4. The platform team verifies the artifact and publishes it to an approved registry.
5. The consumer build pipeline verifies `checksums.sha256` and `sdk-manifest.json`.
6. The application installs or builds the generated package.
7. Runtime configuration supplies the gateway proxy URL and credential.
8. The application calls the generated operation method or uses the generic request method as an escape hatch.

## Generated method surface

Every OpenAPI operation becomes a public client method. Method names come from `operationId`; when it is absent, the generator derives a stable name from the HTTP verb and path. Reserved words and collisions are handled per language.

For example, `GET /orders/{order_id}` with `operationId: getOrder` becomes:

| Language   | Generated method         |
| ---------- | ------------------------ |
| TypeScript | `getOrder(options)`      |
| Python     | `get_order(**kwargs)`    |
| Go         | `GetOrder(ctx, options)` |
| Java       | `getOrder(options)`      |
| C#         | `GetOrderAsync(options)` |
| PHP        | `getOrder($options)`     |

Pass path parameters, query values, request body, headers, timeout, and retry overrides through the language's request-options type. Each package includes `REFERENCE.md` with the exact method, HTTP verb, path, and response model for every operation. `openapi.json` remains the source of truth for request and response schemas.

The generic `request` / `Request` / `RequestAsync` method remains available for dynamic paths and forward-compatible calls. Prefer generated methods for normal application code because they preserve stable operation names and return-model information.

## Export from the CLI

Configure a `kangalctl` context with the Kangal Admin API URL, admin token, and tenant scope. Then export a published API version:

```bash
python scripts/kangalctl.py sdk export \
  --service-id svc-orders \
  --version-id version-1 \
  --gateway-id gw-production \
  --target typescript-fetch \
  --output orders-sdk.zip
```

Supported targets are `typescript-fetch`, `python`, `go`, `java`, `csharp`, and `php`.

## Export through the API

```
GET /portal/services/{service_id}/versions/{version_id}/sdk
    ?tenant_id={tenant_id}
    &gateway_id={gateway_id}
    &target={target}
```

The endpoint requires an authenticated administrator with `developer_portal.manage`. A consumer application must never call this endpoint or embed an Admin API token. The platform team exports the artifact and distributes the verified package through an approved channel.

## Verify the artifact

The ZIP includes:

* generated client source with one method per OpenAPI operation;
* `REFERENCE.md` with the complete method index;
* package metadata for the selected language;
* the immutable `openapi.json` contract;
* `checksums.sha256` for generated files;
* `sdk-manifest.json` with generator, scope, version, and checksum metadata.

Verify checksums before publishing the generated package to an internal package registry. Never execute an artifact that fails integrity verification.

## Configure the runtime

Use the public Kangal gateway **Proxy URL** as `baseUrl`. Supply either the API key or bearer token expected by the gateway route. Keep credentials in an environment variable, workload identity, or secret manager.

Generated clients contain the published `X-Tenant-ID` and `X-Gateway-ID` defaults. Do not override these values unless the platform owner explicitly provides another compatible scope.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kangal.dev/sdks/api-client.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.