OwlectOwlect
Почати безкоштовно

Для розробників · REST API

REST API Owlect

Читайте й змінюйте колекції та предмети користувача Owlect через HTTPS. Кожен запит містить токен доступу OAuth, який користувач надав вашому застосунку, і бачить лише дані цього користувача.

Базова адреса

https://owlect.app/api/v1
v1JSONOAuth 2.1 + PKCEOpenAPI 3.111 ендпоінтівСпецифікація OpenAPI →Переглянути як Markdown →

Швидкий старт

  1. 1

    Зареєструйте застосунок

    Надішліть POST з адресою повернення на ендпоінт реєстрації та збережіть отриманий client_id.

  2. 2

    Отримайте токен

    Відправте користувача на адресу авторизації: він увійде через Google і натисне «Дозволити». Потім обміняйте код на токен доступу.

  3. 3

    Викликайте API

    Додавайте Authorization: Bearer <token> до кожного запиту. Почніть із GET /account.

Автентифікація

Owlect - сервер авторизації OAuth 2.1. Застосунки є публічними клієнтами й підтверджують себе через PKCE, тож секрету, який можна втратити, немає.

1. Зареєструйте клієнт

Адреси повернення - https або http на localhost. Реєстрація відкрита й обмежена за частотою.

bash
curl -X POST https://owlect.app/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My app", "redirect_uris": ["https://myapp.example/callback"]}'

2. Відправте користувача на авторизацію

Використайте response_type=code, code_challenge PKCE S256, свою redirect_uri, значення state і scope="read create update delete" (просіть лише те, що потрібно). Користувач увійде через Google, побачить екран дозволу з адресою вашого застосунку й позначить, що дозволити: перегляд і створення вибрані заздалегідь. Поле scope у відповіді з токеном показує, що надано.

url
https://owlect.app/oauth/authorize?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https%3A%2F%2Fmyapp.example%2Fcallback
  &code_challenge=CODE_CHALLENGE&code_challenge_method=S256
  &scope=read%20create%20update%20delete&state=STATE

3. Обміняйте код

Надішліть POST із кодом і code_verifier на ендпоінт токенів. Ви отримаєте токен доступу (термін: 1 година) і токен оновлення (30 днів), що змінюється при кожному використанні: завжди зберігайте найновіший.

bash
curl -X POST https://owlect.app/api/oauth/token \
  -d grant_type=authorization_code \
  -d code=CODE -d client_id=CLIENT_ID \
  -d redirect_uri=https://myapp.example/callback \
  -d code_verifier=CODE_VERIFIER

4. Викликайте API

Додавайте Authorization: Bearer <access_token>. Коли термін мине, використайте grant_type=refresh_token, щоб отримати нову пару.

bash
curl -X POST https://owlect.app/api/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=REFRESH_TOKEN -d client_id=CLIENT_ID

Області доступу

read

Переглядати ваші колекції та предмети. Завжди увімкнено.

create

Додавати колекції та предмети. Увімкнено за замовчуванням.

update

Змінювати колекції та предмети. Вимкнено, поки ви не позначите.

delete

Видаляти колекції та предмети. Вимкнено, поки ви не позначите.

Особистих API-ключів поки немає: кожен токен з'являється, коли користувач схвалює ваш застосунок, і користувач може будь-коли відкликати його в Налаштування -> Підключені застосунки.

Ендпоінти

Усі ендпоінти приймають і повертають JSON. Ідентифікатори - UUID.

Акаунт

GET/api/v1/account(getAccount)

Тариф і використання, порівняння Free, Plus і Pro (ліміти, можливості, ціна), доступ цього токена, залишок денних лімітів змін і видалень, розміри пакетів, стан підписки (статус, дата продовження чи завершення, посилання для керування) і посилання на сторінки застосунку. Викликайте першим; це не витрачає ліміт.

Без параметрів.

Колекції

GET/api/v1/collections(listCollections)

Усі колекції користувача, нещодавно змінені - першими.

Без параметрів.

POST/api/v1/collections(createCollection)

Створює колекцію. Вбудовані типи отримують стандартні поля, якщо не передано fieldDefinitions. Власний тип (custom) потребує Owlect Plus.

  • nameтілоОбов'язковий

    string, 1-100

    Назва колекції.

  • typeтілоОбов'язковий

    dolls | board_games | coins | stamps | music | pokemon_cards | sneakers | retro_games | funko_pop | lego | comic_books | books | watches | cars | hot_wheels | custom

    Тип колекції. Визначає стандартні поля та пошук у застосунку.

  • descriptionтіло

    string, max 500

    Показується на сторінці колекції.

  • fieldDefinitionsтіло

    array of { key, label, type, options?, required? }

    Власні поля. Не передавайте, щоб отримати стандартні поля типу.

GET/api/v1/collections/{collectionId}(getCollection)

Одна колекція з визначеннями її власних полів. Прочитайте їх перед записом customFieldValues.

  • collectionIdшляхОбов'язковий

    uuid

    Ідентифікатор однієї з колекцій користувача (зі списку колекцій).

PATCH/api/v1/collections/{collectionId}(updateCollection)

Змінює назву, опис або визначення полів. Те, чого ви не надіслали, лишається без змін.

  • collectionIdшляхОбов'язковий

    uuid

    Колекція, яку змінюємо.

  • nameтіло

    string, 1-100

    Нова назва.

  • descriptionтіло

    string, max 500

    Новий опис.

  • fieldDefinitionsтіло

    array of { key, label, type, options?, required? }

    Замінює весь список полів.

DELETE/api/v1/collections/{collectionId}(deleteCollection)

Видаляє колекцію разом з усіма предметами. confirmName має точно збігатися з назвою колекції.

  • collectionIdшляхОбов'язковий

    uuid

    Колекція, яку видаляємо.

  • confirmNameзапитОбов'язковий

    string (the collection's exact name)

    Має точно збігатися з назвою колекції.

Предмети

GET/api/v1/collections/{collectionId}/items(searchItems)

Предмети колекції, найновіші першими, з необов'язковим пошуком за назвою і фільтром «на продаж». Пагінація через курсор.

  • collectionIdшляхОбов'язковий

    uuid

    Колекція для пошуку.

  • queryзапит

    string, max 200

    Пошук за назвою предмета без урахування регістру.

  • forSaleзапит

    boolean

    true - предмети на продаж, false - решта.

  • wantedзапит

    boolean (true = wishlist items only, false = owned only)

    true - бажані предмети (список бажаного), false - ті, що у вас є.

  • viewзапит

    full (default: every field) | summary (id, name, quantity, bggItemId, wanted)

    full (за замовчуванням) повертає всі поля; summary лише id, назву, кількість, bggItemId і wanted, тож уся колекція вміщується в один виклик.

  • limitзапит

    integer; full: 1-50, default 20; summary: 1-500, default 500

    Предметів на сторінці: full до 50 (за замовчуванням 20), summary до 500 (за замовчуванням 500).

  • cursorзапит

    string (nextCursor from the previous page)

    nextCursor з попередньої сторінки. Для першої сторінки не передавайте.

POST/api/v1/collections/{collectionId}/items(createItems)

Додає до 50 предметів за один запит. Значення власних полів спершу перевіряються; якщо хоч один предмет некоректний, нічого не зберігається.

  • collectionIdшляхОбов'язковий

    uuid

    Колекція, до якої додаємо.

  • itemsтілоОбов'язковий

    array, 1-50 items

    Предмети для створення.

  • items[].nameтілоОбов'язковий

    string, 1-200

    Назва предмета.

  • items[].descriptionтіло

    string, max 1000

    Довільні нотатки.

  • items[].quantityтіло

    integer 1-999

    Скільки примірників у вас є.

  • items[].customFieldValuesтіло

    object: field key -> string | number | boolean | null

    Значення за ключами полів колекції (спершу прочитайте колекцію, щоб їх дізнатися). Невідомі ключі відхиляються зі списком допустимих.

  • items[].forSaleтіло

    boolean

    Виставляє предмет на продаж.

  • items[].wantedтіло

    boolean (true = wishlist item; not with forSale: true)

    Позначає предмет як бажаний (у списку бажаного), а не наявний. Бажаний предмет не може бути на продаж.

  • items[].salePriceтіло

    integer (whole currency units) | null

    Ціна в цілих одиницях, наприклад 40 для $40.

  • items[].saleCurrencyтіло

    currency code, e.g. USD, EUR, UAH

    Валюта ціни. За замовчуванням USD.

  • items[].completenessтіло

    complete | incomplete | partial | sealed | unknown | null

    Чи предмет повний, запечатаний тощо.

  • items[].barcodeтіло

    string, max 64 | null

    EAN, UPC або ISBN.

  • items[].coverUrlтіло

    https URL | null

    Посилання на зображення обкладинки. Зберігається як посилання, файл не завантажується.

DELETE/api/v1/collections/{collectionId}/items(deleteItems)

Видаляє до 25 предметів з колекції.

  • collectionIdшляхОбов'язковий

    uuid

    Колекція, до якої належать предмети.

  • idsзапитОбов'язковий

    comma-separated uuids

    Ідентифікатори предметів для видалення через кому.

GET/api/v1/items/{itemId}(getItem)

Один предмет з усіма полями.

  • itemIdшляхОбов'язковий

    uuid

    Ідентифікатор предмета (зі списку чи пошуку в колекції).

PATCH/api/v1/items/{itemId}(updateItem)

Змінює лише надіслані поля. customFieldValues об'єднуються за ключем, а null очищує поле.

  • itemIdшляхОбов'язковий

    uuid

    Предмет, який змінюємо.

  • nameтіло

    string, 1-200

    Нова назва.

  • descriptionтіло

    string, max 1000

    Довільні нотатки.

  • quantityтіло

    integer 1-999

    Скільки примірників у вас є.

  • customFieldValuesтіло

    object: field key -> string | number | boolean | null

    Значення за ключами полів колекції (спершу прочитайте колекцію, щоб їх дізнатися). Невідомі ключі відхиляються зі списком допустимих.

  • forSaleтіло

    boolean

    Виставляє предмет на продаж.

  • wantedтіло

    boolean (true = wishlist item; not with forSale: true)

    Позначає предмет як бажаний (у списку бажаного), а не наявний. Бажаний предмет не може бути на продаж.

  • salePriceтіло

    integer (whole currency units) | null

    Ціна в цілих одиницях, наприклад 40 для $40.

  • saleCurrencyтіло

    currency code, e.g. USD, EUR, UAH

    Валюта ціни. За замовчуванням USD.

  • completenessтіло

    complete | incomplete | partial | sealed | unknown | null

    Чи предмет повний, запечатаний тощо.

  • barcodeтіло

    string, max 64 | null

    EAN, UPC або ISBN.

  • coverUrlтіло

    https URL | null

    Посилання на зображення обкладинки. Зберігається як посилання, файл не завантажується.

Приклади

Замініть $TOKEN на токен доступу, а ідентифікатори - на справжні.

Список колекцій

bash
curl https://owlect.app/api/v1/collections \
  -H "Authorization: Bearer $TOKEN"

Додати предмети до колекції

bash
curl -X POST https://owlect.app/api/v1/collections/COLLECTION_ID/items \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items": [
    {"name": "Wingspan", "customFieldValues": {"game_type": "Base Game"}},
    {"name": "Scythe", "quantity": 2}
  ]}'

Знайти предмети на продаж

bash
curl "https://owlect.app/api/v1/collections/COLLECTION_ID/items?forSale=true&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Виставити предмет на продаж

bash
curl -X PATCH https://owlect.app/api/v1/items/ITEM_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"forSale": true, "salePrice": 40, "saleCurrency": "USD"}'

Помилки

Помилки мають єдиний формат JSON і відповідний HTTP-статус. `code` стабільний; `message` - для людей і може змінюватися.

json
{
  "error": {
    "code": "invalid_input",
    "message": "Unknown field \"publsher\". This collection's fields are: ...",
    "details": {
      "validKeys": [
        "publisher",
        "players"
      ]
    }
  }
}
401 unauthorized
Токена немає, або він недійсний, прострочений чи відкликаний. Оновіть його або знову пройдіть авторизацію.
403 insufficient_scope
Токен має лише область read.
403 plan_limit
Досягнуто ліміту тарифу користувача. У details - ліміт і upgradeUrl.
404 not_found
У цього користувача немає такої колекції чи предмета.
409 confirmation_required
confirmName не збігся з назвою колекції.
413 payload_too_large
Тіло запиту більше за 1 МБ. Надсилайте менше предметів за раз.
422 invalid_input
Вхідні дані не пройшли перевірку, або тіло містить ключ, якого ендпоінт не знає (details.unknownKeys). Якщо невідоме власне поле, details.validKeys містить ключі полів колекції.
429 rate_limited
Забагато запитів. Зачекайте стільки, скільки вказано в заголовку Retry-After.
503 unavailable
Тимчасова проблема на боці Owlect. Повторіть трохи згодом.
500 internal
Неочікувана помилка. Повторіть; якщо не минає, напишіть у підтримку.

Пагінація

GET /collections/{collectionId}/items повертає { items, nextCursor }. Передайте nextCursor як ?cursor=, щоб отримати наступну сторінку; на останній сторінці він null. Сторінки стабільні навіть під час запису.

Ліміти

Ліміти діють для кожного підключеного застосунку (дозволу). REST API і MCP-сервер ділять їх між собою.

  • 120 запитів на хвилину.
  • 500 запитів на зміну на день, з них до 20 на видалення.
  • На користувача, разом для всіх його підключених застосунків: 1000 запитів на зміну і 40 на видалення на день.
  • До 50 предметів за запит на створення і 25 за запит на видалення.
  • Ліміти тарифу на предмети й колекції діють так само, як у застосунку.
  • Кожна автентифікована відповідь містить заголовки RateLimit-Policy (хвилинна квота, напр. "minute";q=120;w=60) і RateLimit (скільки залишилося і через скільки секунд скинеться, напр. "minute";r=57;t=18) за чернеткою IETF про заголовки RateLimit. Відповідь 429 також містить Retry-After. Денні ліміти повертає GET /account.

Custom GPT (дії ChatGPT)

Custom GPT може використовувати API Owlect як дію (Action).

Специфікація OpenAPI

https://owlect.app/api/v1/openapi.json
  1. 1У редакторі GPT відкрийте Actions -> Create new action -> Import from URL і вставте адресу специфікації OpenAPI.
  2. 2У розділі Authentication оберіть OAuth. Authorization URL: https://owlect.app/oauth/authorize. Token URL: https://owlect.app/api/oauth/token. Scope: read create update delete (користувач однаково обирає на екрані дозволу). Token exchange method: Default (POST request).
  3. 3Введіть client ID і client secret, які Owlect видасть для вашого GPT, і скопіюйте callback URL, який покаже ChatGPT, щоб його зареєстрували.

Дії GPT використовують секрет клієнта, який Owlect видає окремо для кожного GPT на запит. Напишіть на support@owlect.app і додайте callback URL вашого GPT.

Версії

Це v1, і версія є частиною шляху. Нові ендпоінти, необов'язкові параметри чи поля відповіді не ламають клієнтів; зміни, що можуть зламати клієнт, виходять лише в новій версії. Перш ніж ендпоінт чи версію буде вилучено, щонайменше 6 місяців вони відповідають із заголовком Deprecation (RFC 9745) і заголовком Sunset (RFC 8594) з датою вилучення, а зміну оголошуємо на сторінці оновлень. Зараз нічого не застаріло.