> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plungeai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# plungeai-sdk-setup

> Install and use the official PlungeAI One API SDKs — TypeScript `@plungeai/one-api` (npm), Python `plungeai` (PyPI), Go `github.com/PlungeAI/plungeai-go` and Rust `plungeai` (crates.io) — for the One API at https://api.plungeai.com: key from PLUNGEAI_API_KEY, first whoami and agents.execute call…


Install and use the official PlungeAI One API SDKs — TypeScript `@plungeai/one-api` (npm), Python `plungeai` (PyPI), Go `github.com/PlungeAI/plungeai-go` and Rust `plungeai` (crates.io) — for the One API at https://api.plungeai.com: key from PLUNGEAI_API_KEY, first whoami and agents.execute call, discovery-first lookups, typed errors, retries, streams, pages and idempotency. Use when a user or agent writes code (an app, a script, a backend, a generated project) that calls PlungeAI in TypeScript, Python, Go or Rust and wants a typed client instead of raw HTTP, or asks "is there a PlungeAI SDK", "pip install plungeai", "npm @plungeai/one-api", "PlungeAI Go/Rust client". Every SDK method is generated from the live contract at https://api.plungeai.com/v1/openapi.json. Wire-level API and curl: `plungeai-api-setup`; models plane with the OpenAI SDK: `plungeai-models`; terminal: `plungeai-cli-setup`; MCP: `plungeai-mcp-setup`.

[Download zip](https://skills.plungeai.com/plungeai-sdk-setup.zip) · [View raw SKILL.md](https://skills.plungeai.com/plungeai-sdk-setup/SKILL.md)

Four official SDKs for the One API (`https://api.plungeai.com`), one shape: a client that reads the key from
`PLUNGEAI_API_KEY`, one method per operation generated from `https://api.plungeai.com/v1/openapi.json` (every
route in the spec has a method), typed errors, retries, streams and pages. All four target One API 2.4.0, package
version 1.0.0. The wire-level API (curl, headers, error codes): `plungeai-api-setup`.

## Pick a language

| Language | Package | Install | Runtime deps |
|---|---|---|---|
| TypeScript | `@plungeai/one-api` (npm) | `npm install @plungeai/one-api` | none (ESM + CJS; Node 20+, Deno, Bun, Workers) |
| Python | `plungeai` (PyPI) | `pip install plungeai` | `httpx`; Python ≥ 3.10; sync `PlungeAI` + `AsyncPlungeAI` |
| Go | `github.com/PlungeAI/plungeai-go` | `go get github.com/PlungeAI/plungeai-go` | standard library only; Go ≥ 1.24 |
| Rust | `plungeai` (crates.io) | `cargo add plungeai tokio --features tokio/full` | `reqwest` (rustls) on `tokio`; Rust ≥ 1.85 |

None of the four is on its registry yet. Until its tag is published, build from `sdk/<dir>/` in the platform repository:

- `@plungeai/one-api` is not on npm yet: until the `one-api-v1.0.0` tag is published, build from `sdk/one-api-client/` (`npm ci && npm run build`).
- `plungeai` is not on PyPI yet: until the `one-api-python-v1.0.0` tag is published, build from `sdk/one-api-python/` (`bash scripts/build.sh`, then `pip install target/sdk-py-build/*.whl`).
- `github.com/PlungeAI/plungeai-go` is not on the Go proxy yet: until the `one-api-go-v1.0.0` tag is published, `replace` it with `sdk/one-api-go/`.
- `plungeai` is not on crates.io yet: until the `one-api-rust-v1.0.0` tag is published, depend on the path `sdk/one-api-rust/`.

Release check: `npm view @plungeai/one-api version` · `pip index versions plungeai` ·
`go list -m -versions github.com/PlungeAI/plungeai-go` · `cargo search plungeai`.

## Key

One `ozk_` key for every plane — create it in **Dashboard → One API → Keys** (https://dashboard.plungeai.com).
Export it as `PLUNGEAI_API_KEY`; every SDK reads that variable (the CLI too). The curl examples in the other
skills use `$PLUNGE_API_KEY` — same key, different variable name. Never hardcode it, log it, or ship it to a
browser (the TypeScript client refuses browsers unless you pass `dangerouslyAllowBrowser: true`).

```bash
export PLUNGEAI_API_KEY=ozk_YOUR_KEY
```

## First call

TypeScript:

```ts
import PlungeAI from '@plungeai/one-api'

const client = new PlungeAI()
const me = await client.whoami()
const run = await client.agents.execute('one-agent', { prompt: 'Reply with exactly the word: pong', max_tokens: 32 })
```

Python:

```python
from plungeai import PlungeAI

client = PlungeAI()  # or AsyncPlungeAI() — same methods, awaited
me = client.whoami()
run = client.agents.execute("one-agent", prompt="Reply with exactly the word: pong", max_tokens=32)
```

Go:

```go
import "github.com/PlungeAI/plungeai-go"

client := plungeai.NewClient() // plungeai.WithAPIKey(…) to override PLUNGEAI_API_KEY
ctx := context.Background()
me, err := client.Whoami(ctx)
run, err := client.Agents.Execute(ctx, "one-agent", plungeai.AgentExecuteParams{Prompt: "Reply with exactly the word: pong", MaxTokens: 32})
```

Rust:

```rust
use plungeai::{types::*, Client};

let client = Client::new()?; // or Client::builder().api_key(…).build()?
let me = client.whoami().await?;
let run = client
    .agents()
    .execute("one-agent", &AgentExecuteParams { prompt: Some("Reply with exactly the word: pong".into()), max_tokens: Some(32), ..Default::default() })
    .await?;
```

## Discover before you call

`one-agent` above is the general-purpose agent; every other agent, tool or workflow id comes from a live lookup,
never from memory. Discovery is one SDK call (`GET /v1/discovery/search` on the wire):

```ts
const hits = await client.discovery.search({ q: 'web search', kind: 'agents', limit: 3 })   // TypeScript
```
```python
hits = client.discovery.search(q="web search", kind="agents", limit=3)                     # Python
```
```go
hits, err := client.Discovery.Search(ctx, plungeai.DiscoverySearchParams{Q: "web search", Kind: "agents", Limit: 3})
```
```rust
let hits = client.discovery().search(&DiscoverySearchParams { q: Some("web search".into()), kind: Some(DiscoverySearchParamsKind::Agents), limit: Some(3), ..Default::default() }).await?;
```

Then read the tool contract (`GET /v1/tools/{id}`; `client.tools.retrieve(id)` in TypeScript) before executing. A 404 on an id means
re-discover, not retry.

## What every SDK gives you

| Concern | Behaviour (TS · Python · Go · Rust) |
|---|---|
| Errors | One class per status — TS/Python `BadRequestError` … `NotFoundError`, `ConflictError` (409), `FailedDependencyError` (424, carries `connect.link` — where to connect the missing account), `RateLimitError`, `InternalServerError` (≥ 500); Go one `*plungeai.Error` with `StatusCode`, `Code`, `RequestID`, `Connect`; Rust `Error::Api(ApiError)` with `status`, `code`, `request_id`, `connect` |
| Retries | 2 by default, exponential backoff honouring `Retry-After`, on connection errors, timeouts, 408, 429, ≥ 500. **Never on 409 or 424** — those are semantic answers (`approval_required`, `duplicate_execution_id`, a missing connection); surface them |
| Timeout | 10 minutes per request, configurable on the client and per call |
| Streams | SSE: `workflows.executeInlineStream` / `execute_inline_stream` / `ExecuteInlineStream`; `stream: true` operations have a streaming form (`stream=True`, `…Streaming`, `…_stream`) |
| Pages | Offset pages; `for await` / `for` / `…AutoPaging` / `into_stream()` walk every page |
| Raw response | TS `.withResponse()` / `.asResponse()` · Python `with_raw_response` · Go `WithResponseInto(&raw)` · Rust `…_raw`; plus `get/post/…` escape hatches |
| Idempotency | `idempotencyKey` · `idempotency_key` · `WithIdempotencyKey` · `RequestOptions::idempotency_key` → sent as `x-trace-id`, the run's execution id; a replay answers 409 `duplicate_execution_id` instead of starting twice |

Per-language detail (async client, streaming, pagination, error tables, options forms, raw responses):
[`references/per-language.md`](/skills/plungeai-sdk-setup/references/per-language).

## Hand-over

- `plungeai-api-setup` — the wire-level One API: auth headers, curl, error codes, codegen for other languages.
- `plungeai-agents` — agent execution in depth (sync/async, results polling, trust fences).
- `plungeai-workflows` — CNL workflows: author, save, run, stream.
- `plungeai-models` — the OpenAI-wire models plane; the OpenAI SDK also works there with base URL `https://api.plungeai.com/v1`.
- `plungeai-cli-setup` — the same platform from a terminal or CI.
- `plungeai-mcp-setup` — the same platform as an MCP server for a live agent.

## Reference pages

<CardGroup cols={2}>
<Card title="Per-language detail — the four One API SDKs" icon="file-text" href="/skills/plungeai-sdk-setup/references/per-language">
Shared by all four: the key comes from PLUNGEAIAPIKEY; base URL https://api.plungeai.com; retries 2 with exponential backoff honouring Retry-After on…
</Card>
</CardGroup>