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

REST API Owlect

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

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

https://owlect.app/api/v1

v1JSONOAuth 2.1 + PKCEOpenAPI 3.111 ендпоінтівСпецифікація OpenAPI →Переглянути як Markdown →

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

1
Зареєструйте застосунок
Надішліть POST з адресою повернення на ендпоінт реєстрації та збережіть отриманий client_id.
2
Отримайте токен
Відправте користувача на адресу авторизації: він увійде через Google і натисне «Дозволити». Потім обміняйте код на токен доступу.
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)

Тариф користувача і скільки з лімітів предметів і колекцій уже використано.

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

Колекції

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? }
Власні поля. Не передавайте, щоб отримати стандартні поля типу.

Параметр	Де	Тип	Обов'язковий	Опис
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
Ідентифікатор однієї з колекцій користувача (зі списку колекцій).

Параметр	Де	Тип	Обов'язковий	Опис
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? }
Замінює весь список полів.

Параметр	Де	Тип	Обов'язковий	Опис
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)
Має точно збігатися з назвою колекції.

Параметр	Де	Тип	Обов'язковий	Опис
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 - решта.
limitзапит
integer 1-50, default 20
Предметів на сторінці.
cursorзапит
string (nextCursor from the previous page)
nextCursor з попередньої сторінки. Для першої сторінки не передавайте.

Параметр	Де	Тип	Обов'язковий	Опис
collectionId	шлях	uuid	так	Колекція для пошуку.
query	запит	string, max 200	ні	Пошук за назвою предмета без урахування регістру.
forSale	запит	boolean	ні	true - предмети на продаж, false - решта.
limit	запит	integer 1-50, default 20	ні	Предметів на сторінці.
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[].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
Посилання на зображення обкладинки. Зберігається як посилання, файл не завантажується.

Параметр	Де	Тип	Обов'язковий	Опис
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[].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
Ідентифікатори предметів для видалення через кому.

Параметр	Де	Тип	Обов'язковий	Опис
collectionId	шлях	uuid	так	Колекція, до якої належать предмети.
ids	запит	comma-separated uuids	так	Ідентифікатори предметів для видалення через кому.

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

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

itemIdшляхОбов'язковий
uuid
Ідентифікатор предмета (зі списку чи пошуку в колекції).

Параметр	Де	Тип	Обов'язковий	Опис
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
Виставляє предмет на продаж.
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
Посилання на зображення обкладинки. Зберігається як посилання, файл не завантажується.

Параметр	Де	Тип	Обов'язковий	Опис
itemId	шлях	uuid	так	Предмет, який змінюємо.
name	тіло	string, 1-200	ні	Нова назва.
description	тіло	string, max 1000	ні	Довільні нотатки.
quantity	тіло	integer 1-999	ні	Скільки примірників у вас є.
customFieldValues	тіло	object: field key -> string \| number \| boolean \| null	ні	Значення за ключами полів колекції (спершу прочитайте колекцію, щоб їх дізнатися). Невідомі ключі відхиляються зі списком допустимих.
forSale	тіло	boolean	ні	Виставляє предмет на продаж.
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 за запит на видалення.
Ліміти тарифу на предмети й колекції діють так само, як у застосунку.

Custom GPT (дії ChatGPT)

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

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

https://owlect.app/api/v1/openapi.json

1У редакторі GPT відкрийте Actions -> Create new action -> Import from URL і вставте адресу специфікації OpenAPI.
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Введіть client ID і client secret, які Owlect видасть для вашого GPT, і скопіюйте callback URL, який покаже ChatGPT, щоб його зареєстрували.

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

Версії

Це v1. Нові ендпоінти, необов'язкові параметри чи поля відповіді не ламають клієнтів; зміни, що можуть зламати клієнт, виходять у новій версії з попередженням.