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

# TypeScript quickstart

Install the FLORA TypeScript SDK, set your API key, and run your first Technique from Node.js, then handle pagination, retries and errors.

The `@flora-ai/flora` SDK is a typed wrapper around the [FLORA API](https://docs.flora.ai/api.md). This page takes you from install to a finished Technique run in one script; it runs on the server (Node.js 20+, Deno, Bun or Workers), never in a browser bundle, because it needs your API key.

## Install

```bash
npm install @flora-ai/flora@^0.21.1
# pnpm add @flora-ai/flora@^0.21.1
# yarn add @flora-ai/flora@^0.21.1
```

{% hint style="info" %}
The examples in these docs need `@flora-ai/flora` 0.21 or later. Check your version with `npm ls @flora-ai/flora`.
{% endhint %}

## Configure

Set your API key in the environment. Create one in **Settings → API Keys** (see [Authentication](https://docs.flora.ai/api/platform/authentication.md)).

```bash
export FLORA_API_KEY="ak_XXXX"
```

The client reads `FLORA_API_KEY` automatically:

```ts
import { FloraClient } from "@flora-ai/flora"

const client = new FloraClient()
```

You can also pass the key explicitly: `new FloraClient({ apiKey: process.env.FLORA_API_KEY })`.

## First run, end to end

Find a Technique, read its inputs and price, start a run and wait for the result. Save this as `first-run.mts` and run it with a Technique slug or ID, for example `npx tsx first-run.mts portrait-enhancer`. A Technique's slug is the last part of its URL in FLORA (`https://app.flora.ai/techniques/{slug}`); its ID (`tech_...`) comes from the list in step 1. Both work anywhere the SDK asks for `techniqueId`.

```ts
import { FloraClient } from "@flora-ai/flora"

const client = new FloraClient()
const slug = process.argv[2] ?? "your-technique-slug"

// 1. List the Techniques your key can see
const page = await client.techniques.list({ limit: 20 })
for (const technique of page.data) console.log(technique.technique_id, technique.name)

// 2. Read the Technique's inputs and its price per run (US dollars)
const technique = await client.techniques.retrieve({ techniqueId: slug })
console.log(technique.inputs, `$${technique.run_cost} per run`)

// 3. Start a run. This example fills the first text input; match every
//    required input's id and type from technique.inputs.
const textInput = technique.inputs.find((input) => input.type === "text")
if (!textInput) throw new Error(`${slug} has no text input`)

const run = await client.techniques.runs.create({
  techniqueId: slug,
  inputs: [{ id: textInput.id, type: "text", value: "Smart living, simple. Warm minimalism." }],
  mode: "async",
})

// 4. Poll until the run finishes
let result = await client.techniques.runs.retrieve({ techniqueId: slug, runId: run.run_id })
while (result.status === "pending" || result.status === "running") {
  await new Promise((resolve) => setTimeout(resolve, 15_000))
  result = await client.techniques.runs.retrieve({ techniqueId: slug, runId: run.run_id })
}

if (result.status === "completed") {
  for (const output of result.outputs ?? []) console.log(output.url)
  console.log(`Charged $${result.charged_cost}`)
} else {
  console.error("Run failed:", result.error_code, result.error_message)
}
```

Each poll is one request against your workspace's rate limit, so wait about 15 seconds between polls. To skip polling, pass a `callback_url` and let FLORA call you; see [Webhooks](https://docs.flora.ai/api/platform/webhooks.md).

## Pagination

List methods return a page you can iterate across every page with `for await`:

```ts
for await (const technique of await client.techniques.list({ limit: 50 })) {
  console.log(technique.technique_id, technique.name)
}
```

For a single page, read `data` and check for more:

```ts
const page = await client.techniques.list({ limit: 10 })
console.log(page.data, page.hasNextPage())
```

## Idempotency

Technique runs accept an `idempotency_key` in the body. Reusing a key in the same workspace returns the run it first created instead of starting a new one:

```ts
const run = await client.techniques.runs.create({
  techniqueId: slug,
  inputs: [{ id: textInput.id, type: "text", value: "Spring launch, DE" }],
  mode: "async",
  idempotency_key: "spring-launch-DE",
})
```

Every other create call takes an `Idempotency-Key` header, which you pass in the request options:

```ts
await client.projects.create(
  { workspace_id: "ws_abc123", name: "Spring launch" },
  { headers: { "Idempotency-Key": "create-spring-launch" } },
)
```

See [Idempotency](https://docs.flora.ai/api/platform/idempotency.md) for how the two differ.

## Errors and retries

The SDK throws `FloraError` for any non-2xx response, with a subclass per status (`Flora.BadRequestError`, `Flora.PaymentRequiredError`, `Flora.TooManyRequestsError` and so on). The API's error code is on `err.body`, and `err.requestId` holds the `Flora-Request-Id` header that support asks for:

```ts
import { Flora, FloraClient, FloraError } from "@flora-ai/flora"

const client = new FloraClient()

try {
  await client.techniques.runs.create({ techniqueId: "your-technique-slug", inputs: [], mode: "async" })
} catch (err) {
  if (err instanceof FloraError) {
    const apiError = (err.body as { error?: { code?: string; message?: string } } | undefined)?.error
    console.error(err.statusCode, apiError?.code, apiError?.message, err.requestId)
    if (err instanceof Flora.PaymentRequiredError) {
      // insufficient_credits: the workspace can't cover this run
    }
  } else {
    throw err
  }
}
```

By default the SDK retries `408`, `429` and `5xx` responses twice, honoring `Retry-After`. Pass `{ maxRetries: 0 }` as the request options on a call if you want to handle retries yourself. See [Errors](https://docs.flora.ai/api/platform/errors.md) for every code.

## What's next

* [Authentication](https://docs.flora.ai/api/platform/authentication.md): key scopes, rotation and security.
* [Generations](https://docs.flora.ai/api/guides/generations.md): run a single model without a Technique.
* [Recipes](https://docs.flora.ai/api/recipes.md): end-to-end patterns in code.
* [FLORA API reference](https://docs.flora.ai/api/reference.md): every endpoint, parameter and response type.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/api/quickstarts/typescript.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
