Quickstart

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.

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

curl https://getrefract.app/v1/me \
  -H "Authorization: Bearer $REFRACT_KEY"

JavaScript

const me = await fetch("https://getrefract.app/v1/me", {
  headers: { Authorization: `Bearer ${process.env.REFRACT_KEY}` },
}).then((res) => res.json());

Python

import os, requests

me = requests.get(
    "https://getrefract.app/v1/me",
    headers={"Authorization": f"Bearer {os.environ['REFRACT_KEY']}"},
).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

curl "https://getrefract.app/v1/library?status=in_progress" \
  -H "Authorization: Bearer $REFRACT_KEY"

JavaScript

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

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"]

{
  "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, so each member approves your app and can revoke it.
• Read the conventions: ids, dates, statuses.
• Browse every endpoint in the API reference.