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

# SDKs

Official TypeScript, Python, and Go libraries for the Pylon API

Pylon has official SDKs for TypeScript, Python, and Go. They cover every endpoint in the [API Reference](/pylon-docs/developer/api/api-reference.md), with types for every request and response, and handle authentication, pagination, and retries for you.

{% hint style="warning" %}
The SDKs are in alpha. Their interfaces may change between `0.x` releases, so pin the version you install.
{% endhint %}

| Language                  | Package                                                                               | Source                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| TypeScript and JavaScript | [`@usepylon/sdk`](https://www.npmjs.com/package/@usepylon/sdk) on npm                 | [pylon-labs/pylon-typescript](https://github.com/pylon-labs/pylon-typescript) |
| Python                    | [`usepylon`](https://pypi.org/project/usepylon/) on PyPI                              | [pylon-labs/pylon-python](https://github.com/pylon-labs/pylon-python)         |
| Go                        | [`github.com/pylon-labs/pylon-go`](https://pkg.go.dev/github.com/pylon-labs/pylon-go) | [pylon-labs/pylon-go](https://github.com/pylon-labs/pylon-go)                 |

## Install

{% tabs %}
{% tab title="TypeScript" %}

```bash
npm install @usepylon/sdk
```

Requires Node.js 18 or later. The package ships both ES module and CommonJS builds.
{% endtab %}

{% tab title="Python" %}

```bash
pip install usepylon
```

Requires Python 3.9 or later. An `AsyncPylon` client is included for `asyncio`.
{% endtab %}

{% tab title="Go" %}

```bash
go get github.com/pylon-labs/pylon-go
```

Requires Go 1.22 or later.
{% endtab %}
{% endtabs %}

## Make your first request

Create an API token as described in [Authentication](/pylon-docs/developer/api/authentication.md), then call `/me` to confirm it works:

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import { PylonClient } from "@usepylon/sdk";

const client = new PylonClient({ token: process.env.PYLON_API_TOKEN });

const { data: me } = await client.me.get();
console.log(me.name);
```

{% endtab %}

{% tab title="Python" %}

```python
import os

from usepylon import Pylon

client = Pylon(token=os.environ["PYLON_API_TOKEN"])

me = client.me.get().data
print(me.name)
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
	"context"
	"fmt"
	"os"

	pylonclient "github.com/pylon-labs/pylon-go/client"
	"github.com/pylon-labs/pylon-go/option"
)

func main() {
	ctx := context.Background()
	client := pylonclient.NewClient(option.WithToken(os.Getenv("PYLON_API_TOKEN")))

	me, err := client.Me.Get(ctx)
	if err != nil {
		panic(err)
	}
	fmt.Println(me.GetData().GetName())
}
```

{% endtab %}
{% endtabs %}

## Choose your region

The client uses the US region unless you set it. If your Pylon tenant is hosted in the EU, select the EU region. See [API regions](/pylon-docs/developer/api/authentication.md#api-regions) for how to tell which one you're on.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import { PylonClient, PylonEnvironment } from "@usepylon/sdk";

const client = new PylonClient({
    token: process.env.PYLON_API_TOKEN,
    environment: PylonEnvironment.Eu,
});
```

{% endtab %}

{% tab title="Python" %}

```python
import os

from usepylon import Pylon
from usepylon.environment import PylonEnvironment

client = Pylon(token=os.environ["PYLON_API_TOKEN"], environment=PylonEnvironment.EU)
```

{% endtab %}

{% tab title="Go" %}

```go
import (
	pylon "github.com/pylon-labs/pylon-go"
	pylonclient "github.com/pylon-labs/pylon-go/client"
	"github.com/pylon-labs/pylon-go/option"
)

client := pylonclient.NewClient(
	option.WithToken(os.Getenv("PYLON_API_TOKEN")),
	option.WithBaseURL(pylon.Environments.Eu),
)
```

{% endtab %}
{% endtabs %}

## How methods map to endpoints

Methods are named after the endpoint path: the resource, then the action. Nested resources become nested clients.

| Endpoint                             | TypeScript                                                   | Python                                                    | Go                                                                                                                 |
| ------------------------------------ | ------------------------------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `GET /issues/{id}`                   | `client.issues.get({ id })`                                  | `client.issues.get(id)`                                   | `client.Issues.Get(ctx, &pylon.IssuesGetRequest{ID: id})`                                                          |
| `POST /issues`                       | `client.issues.create({ ... })`                              | `client.issues.create(...)`                               | `client.Issues.Create(ctx, &pylon.IssuesCreateRequest{...})`                                                       |
| `POST /issues/search`                | `client.issues.search({ filter })`                           | `client.issues.search(filter=...)`                        | `client.Issues.Search(ctx, &pylon.IssuesSearchRequest{Filter: ...})`                                               |
| `GET /knowledge-bases/{id}/articles` | `client.knowledgeBases.articles.list({ knowledge_base_id })` | `client.knowledge_bases.articles.list(knowledge_base_id)` | `client.KnowledgeBases.Articles.List(ctx, &knowledgebases.KnowledgeBasesArticlesListRequest{KnowledgeBaseID: id})` |

In TypeScript, each method takes one object holding the path parameters and request fields under their API names. In Python, path parameters are positional and fields are keyword arguments. In Go, each method takes a `context.Context` and a request struct; request types for nested resources live in that resource's package, such as `knowledgebases`.

Responses keep the API's shape, so the record is under `data` (`GetData()` in Go).

## Pagination

List and search methods return a pager that fetches the next page as you iterate:

{% tabs %}
{% tab title="TypeScript" %}

```typescript
for await (const account of await client.accounts.list({ limit: 100 })) {
    console.log(account.name);
}
```

To work a page at a time, use `page.hasNextPage()` and `page.getNextPage()`. `getNextPage()` loads the next page into the same object.
{% endtab %}

{% tab title="Python" %}

```python
for account in client.accounts.list(limit=100):
    print(account.name)
```

To work a page at a time, iterate over `client.accounts.list(limit=100).iter_pages()`.
{% endtab %}

{% tab title="Go" %}

```go
page, err := client.Accounts.List(ctx, &pylon.AccountsListRequest{Limit: pylon.Int64(100)})
if err != nil {
	return err
}
iter := page.Iterator()
for iter.Next(ctx) {
	fmt.Println(iter.Current().GetName())
}
if err := iter.Err(); err != nil {
	return err
}
```

To work a page at a time, use `page.Results` and `page.GetNextPage(ctx)`.
{% endtab %}
{% endtabs %}

See [API conventions](/pylon-docs/developer/api/conventions.md) for how cursors and limits work.

## Handle errors

A request that fails raises an error carrying the HTTP status code and the [error response body](/pylon-docs/developer/api/errors.md). Each status has its own type, such as `NotFoundError`, `UnauthorizedError`, and `TooManyRequestsError`.

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import { Pylon, PylonError } from "@usepylon/sdk";

try {
    await client.issues.get({ id: "issue_id" });
} catch (error) {
    if (error instanceof Pylon.NotFoundError) {
        console.log("Issue not found");
    } else if (error instanceof PylonError) {
        console.log(error.statusCode, error.body);
    }
}
```

{% endtab %}

{% tab title="Python" %}

```python
from usepylon.core.api_error import ApiError
from usepylon.errors import NotFoundError

try:
    client.issues.get("issue_id")
except NotFoundError:
    print("Issue not found")
except ApiError as error:
    print(error.status_code, error.body)
```

{% endtab %}

{% tab title="Go" %}

```go
_, err := client.Issues.Get(ctx, &pylon.IssuesGetRequest{ID: "issue_id"})
var notFound *pylon.NotFoundError
if errors.As(err, &notFound) {
	fmt.Println("Issue not found")
} else if err != nil {
	fmt.Println(err)
}
```

{% endtab %}
{% endtabs %}

## Retries and timeouts

Requests that are rate limited (`429`) or hit a server error (`5xx`) are retried with backoff, waiting as long as the `Retry-After` header asks. Requests that create something aren't retried, so a retry can't create a duplicate. See [Rate limits](/pylon-docs/developer/api/rate-limits.md) for the limits themselves.

In TypeScript and Python, requests time out after 60 seconds and are retried up to 2 times. In Go, set a timeout with the `context` you pass in. You can change these for the whole client or for one request:

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const client = new PylonClient({
    token: process.env.PYLON_API_TOKEN,
    timeoutInSeconds: 30,
    maxRetries: 0,
});

await client.issues.get({ id: "issue_id" }, { maxRetries: 0 });
```

{% endtab %}

{% tab title="Python" %}

```python
client = Pylon(token=os.environ["PYLON_API_TOKEN"], timeout=30, max_retries=0)

client.issues.get("issue_id", request_options={"max_retries": 0})
```

{% endtab %}

{% tab title="Go" %}

```go
client := pylonclient.NewClient(
	option.WithToken(os.Getenv("PYLON_API_TOKEN")),
	option.WithoutRetries(),
)

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

_, err := client.Issues.Get(ctx, &pylon.IssuesGetRequest{ID: "issue_id"}, option.WithMaxAttempts(1))
```

{% endtab %}
{% endtabs %}

## Report a problem

Open an issue on the SDK's GitHub repository: [pylon-typescript](https://github.com/pylon-labs/pylon-typescript/issues), [pylon-python](https://github.com/pylon-labs/pylon-python/issues), or [pylon-go](https://github.com/pylon-labs/pylon-go/issues).


---

# 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.usepylon.com/pylon-docs/developer/api/sdks.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.