# Quickstart

> Create a personal key, ask the API who you are, then list what you are watching.

## Which credential do you need?

| Who runs the code | Credential | Where it comes from |
|---|---|---|
| **You, for yourself**: a script, a dashboard | Personal key, `rfk_…` | The app: Access and connected apps |
| **Your app, for other members** | OAuth 2.1 with PKCE | Register an app in the same screen |
| **A TV, a console or a terminal** | Device code | The member approves on getrefract.app/device |

This page uses a personal key: it is the fastest way to a first answer.

## 1. Create a personal key

In the Refract app, open **Access and connected apps** from the Integrations screen, then create a key.
Pick the scopes your script needs: for this page, `profile:read` and `library:read`. The key starts with `rfk_`
and is shown once.

:::tip[Keep it out of your code]
Store the key in an environment variable such as `REFRACT_KEY`. You can revoke it from the same screen at any time.
:::

## 2. Ask who you are

Every request sends the key as a bearer token. `/v1/me` needs the `profile:read` scope.

  **cURL**
```sh
curl https://getrefract.app/v1/me \
  -H "Authorization: Bearer $REFRACT_KEY"
```
  
  **JavaScript**
```js
const me = await fetch("https://getrefract.app/v1/me", {
  headers: { Authorization: `Bearer ${process.env.REFRACT_KEY}` },
}).then((res) => res.json());
```
  
  **Python**
```python

me = requests.get(
    "https://getrefract.app/v1/me",
    headers={"Authorization": f"Bearer {os.environ['REFRACT_KEY']}"},
).json()
```
  

```json
{
  "id": "3f2a9c4e-6b1d-4e8a-9c27-5d0b8e41f6a2",
  "username": "florent",
  "display_name": "Florent",
  "avatar_url": "https://…",
  "bio": null,
  "country": "FR",
  "locale": "fr",
  "timezone": "Europe/Paris",
  "profile_url": "https://getrefract.app/u/florent",
  "created_at": "2025-02-03T21:14:09.120Z"
}
```

## 3. List what you are watching

Filter the library by status. Pages hold 50 titles by default; follow `next_cursor` until `has_more` is `false`.

  **cURL**
```sh
curl "https://getrefract.app/v1/library?status=in_progress" \
  -H "Authorization: Bearer $REFRACT_KEY"
```
  
  **JavaScript**
```js
const headers = { Authorization: `Bearer ${process.env.REFRACT_KEY}` };
let cursor = null;
do {
  const url = new URL("https://getrefract.app/v1/library");
  url.searchParams.set("status", "in_progress");
  if (cursor) url.searchParams.set("cursor", cursor);
  const page = await fetch(url, { headers }).then((res) => res.json());
  for (const item of page.data) console.log(item.title);
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);
```
  
  **Python**
```python
headers = {"Authorization": f"Bearer {os.environ['REFRACT_KEY']}"}
params = {"status": "in_progress"}
while True:
    page = requests.get("https://getrefract.app/v1/library", params=params, headers=headers).json()
    for item in page["data"]:
        print(item["title"])
    if not page["has_more"]:
        break
    params["cursor"] = page["next_cursor"]
```
  

```json
{
  "data": [
    {
      "type": "show",
      "is_anime": false,
      "ids": { "refract": "8b0e5c1a-…", "tmdb": 95396, "imdb": "tt11280740", "tvdb": null },
      "title": "Severance",
      "original_title": "Severance",
      "year": 2022,
      "status": "in_progress",
      "rewatch_count": 0,
      "added_at": "2025-02-03T21:14:09.120Z",
      "updated_at": "2026-10-27T20:41:55.120Z",
      "progress": {
        "watched_episodes": 13,
        "last_watched": { "season": 2, "number": 4 },
        "last_watched_at": "2026-10-27T20:40:00.000Z"
      },
      "revisit": null
    }
  ],
  "next_cursor": "eyJmIjoi…",
  "has_more": true
}
```

## Where to go next

- Shipping an app other people will use? Switch to [Sign in with Refract](/developers/authentication#sign-in-with-refract), so each member approves your app and can revoke it.
- Read the [conventions](/developers/conventions): ids, dates, statuses.
- Browse every endpoint in the [API reference](/developers/reference).