# SDKs and HTTP clients

Source: https://convergingthought.com/docs/sdk-reference/overview

> Choose a client without changing the public job, routing, or billing semantics.



Internalize's HTTP API is the public integration contract. The repository also contains `@internalize/sdk`, a private TypeScript workspace package. There is currently no publicly published npm package or Python SDK to install.

## Available paths [#available-paths]

| Integration              | Availability                              | What it provides                                                             |
| ------------------------ | ----------------------------------------- | ---------------------------------------------------------------------------- |
| Direct HTTP              | Public contract                           | All seven documented endpoints                                               |
| TypeScript workspace SDK | Authorized repository checkouts           | Typed writes, job reads, activation, polling, and agent tool helpers         |
| Python example           | Copyable standard-library code            | HTTP submission and bounded polling                                          |
| Generated client         | Generate from OpenAPI in your own project | Transport and schema types; application semantics remain your responsibility |

Do not run an unverified `npm install internalize` or similarly named package assuming it is this product. Follow the workspace instructions when you have repository access, or use the documented HTTP calls from your own backend.

## Client responsibilities [#client-responsibilities]

Whichever client you choose, your application owns the mapping from users to subjects, the decision to learn a passage, and the durable identity of each operation. Store the idempotency key before submission and the job ID immediately after admission. A process-local variable alone is not enough for recovery after a server restart.

The client must distinguish transport errors from job outcomes. A `202` response is acceptance, a completed polling helper can return a failed job, and `ready` does not necessarily mean activated. Preserve these distinctions in your application state rather than reducing everything to a boolean success flag.

## Base URL and credentials [#base-url-and-credentials]

Use `https://convergingthought.com` as the origin. The TypeScript client accepts that origin as `baseUrl` and supplies `/v1` paths itself. HTTP examples use `INTERNALIZE_BASE_URL` and append the endpoint explicitly.

Keep the API key in a server secret store. Do not expose it to a browser, agent prompt, repository, or client-side environment variable. The public API rejects requests with an Origin header.

## Method coverage [#method-coverage]

The workspace SDK exposes `internalize`, `infer`, `job`, `wait`, and `activate`. It does not currently include convenience methods for listing jobs, subjects, or models. Use authenticated HTTP for those reads; do not infer unimplemented method names from other providers' clients.

Continue with [TypeScript](/docs/sdk-reference/typescript), [Python](/docs/sdk-reference/python), and [Polling and recovery](/docs/sdk-reference/polling). All live examples require an execution-enabled, funded project; the current [hosted preview](/docs/getting-started/availability) remains gated.