api/docs/index.mdx.vel at main · photon-hq/api · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
---
title: "Overview"
description: "Install the Photon API clients for TypeScript, Python, Rust, and Go."
---

The Photon API clients are libraries for TypeScript, Python, Rust, and Go that call
the [Photon API](/api-reference). Each one is generated from the API's public
OpenAPI contract, so every endpoint is a typed method and every request and
response field has a type.

The clients:

- send the `Authorization: Bearer` header on every request: in TypeScript and
  Python you set the header when you create the client, in Rust the client
  attaches the credential you register, and in Go you pass the credential as a
  client option,
- type every request and response with the contract's fields and names,
- retry reads and idempotent writes after transient errors such as `429` and
  `503`,
- report API errors with the problem details the API returns, and
- give you the status, headers, and request ID of a response when you need them.

They do not run OAuth flows, and they leave validation rules such as patterns,
lengths, and ranges to the API. Responses are read leniently, so an installed
client keeps working as the API grows: fields the API adds later are accepted
(TypeScript and Python keep them; Go ignores them; Rust ignores them unless
the object allows extra members), and new enum values are kept rather than
rejected.

## Packages

| Language | Package | Import | Requires |
| --- | --- | --- | --- |
| TypeScript | [`@photon-ai/api`](https://www.npmjs.com/package/@photon-ai/api) | `@photon-ai/api` | Node.js 22 or later, or a modern browser |
| Python | [`photonhq-api`](https://pypi.org/project/photonhq-api/) | `photon_api` | Python 3.11 or later |
| Rust | [`photonhq-api`](https://crates.io/crates/photonhq-api) | `photon_ai_api` | Rust 1.88 or later, with Tokio |
| Go | [`github.com/photon-hq/api/packages/go`](https://pkg.go.dev/github.com/photon-hq/api/packages/go) | `photonapi` | Go 1.25 or later |

The four packages share one version number and are released together. See
[Versioning](/api-client/versioning).

## Install

<CodeGroup>
```sh TypeScript
npm install @photon-ai/api
```

```sh Python
pip install photonhq-api
```

```sh Rust
cargo add photonhq-api
cargo add tokio --features macros,rt-multi-thread
```

```sh Go
go get github.com/photon-hq/api/packages/go
```
</CodeGroup>

The TypeScript client is an ES module. The Python package includes a
synchronous client, `Photon`, and an asynchronous one, `AsyncPhoton`. The Rust
client is async and runs on Tokio; the Rust examples in this guide also use
`#[tokio::main]`, which needs the Tokio features shown above. The Go client
uses only the standard library.

## Source and contract

The clients, the OpenAPI contract they are generated from
([`openapi/openapi.json`](https://github.com/photon-hq/api/blob/main/openapi/openapi.json)),
and the [changelog](https://github.com/photon-hq/api/blob/main/CHANGELOG.md)
are in [photon-hq/api](https://github.com/photon-hq/api) on GitHub. Report
bugs there as [issues](https://github.com/photon-hq/api/issues).

Every endpoint page in the [API reference](/api-reference) shows the call in
TypeScript, Python, Rust, and Go.

## Next steps

<CardGroup cols={2}>
  <Card title="Credentials" icon="key" href="/api-client/credentials">
    Choose a credential and pass it to the client.
  </Card>
  <Card title="Making requests" icon="paper-plane" href="/api-client/making-requests">
    Call an endpoint and read the response.
  </Card>
  <Card title="Errors" icon="triangle-exclamation" href="/api-client/errors">
    Handle API, transport, and response errors.
  </Card>
  <Card title="Retries and timeouts" icon="rotate" href="/api-client/retries-and-timeouts">
    Know what the clients retry and how to configure it.
  </Card>
</CardGroup>