Интегрируйте поиск без догадок

Быстрый старт

Получение доступа

1. Зарегистрируйтесь и подтвердите email по одноразовой ссылке. Если письмо не пришло, используйте повторную отправку; ответ одинаков для известных и неизвестных адресов.
2. Войдите в кабинет и откройте Профиль → API-ключи.
3. Создайте ключ и сохраните plaintext сразу: повторно он не отображается.

curl -sS 'https://orbisignal.pw/api/v1/me' \
  -H 'Authorization: Bearer YOUR_ORB_TOKEN'

Create → confirm → report

Создание поиска ничего не списывает и возвращает одноразовый confirm_token. Подтверждение списывает текущую цену поиска и запускает провайдера. Проверяйте актуальные цену и баланс через /tariffs и /balance; значение настройки сейчас: $0.30.

# 1. Create
curl -sS -X POST 'https://orbisignal.pw/api/v1/searches' \
  -H 'Authorization: Bearer YOUR_ORB_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"type":"email","query":"ada@example.com"}'

# 2. Confirm: подставьте id и confirm_token из create
curl -sS -X POST 'https://orbisignal.pw/api/v1/searches/SEARCH_ID/confirm' \
  -H 'Authorization: Bearer YOUR_ORB_TOKEN' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  -d '{"confirm_token":"CONFIRM_TOKEN"}'

# 3. Получите report_id из confirm или GET поиска
curl -sS 'https://orbisignal.pw/api/v1/reports/REPORT_ID' \
  -H 'Authorization: Bearer YOUR_ORB_TOKEN'

Idempotency-Key: обязателен для confirm, 1–120 символов. Генерируйте новый уникальный ключ для логической операции и повторяйте тот же ключ при сетевом retry. Он уникален в пределах пользователя; повтор возвращает текущее состояние исходного поиска без второго списания.

Python

import uuid
import httpx

base = "https://orbisignal.pw/api/v1"
headers = {"Authorization": "Bearer YOUR_ORB_TOKEN"}
with httpx.Client(base_url=base, headers=headers, timeout=30) as client:
    created = client.post("/searches", json={"type": "email", "query": "ada@example.com"})
    created.raise_for_status()
    search = created.json()
    confirmed = client.post(
        f"/searches/{search['id']}/confirm",
        headers={"Idempotency-Key": str(uuid.uuid4())},
        json={"confirm_token": search["confirm_token"]},
    )
    confirmed.raise_for_status()
    report = client.get(f"/reports/{confirmed.json()['report_id']}")
    report.raise_for_status()

Endpoint reference

Все пользовательские ресурсы изолированы владельцем. Чужой или отсутствующий ID возвращает 404.

Пагинация

limit: 1–100, по умолчанию 20. offset: 0–100000. Ответ содержит items, limit, offset и next_offset; null означает конец списка.

Cookie-authenticated endpoints GET/POST /api/v1/tokens и DELETE /api/v1/tokens/{id} предназначены для кабинета и требуют session cookie плюс CSRF header для изменений. Для внешних интеграций используйте выданный Bearer-ключ, а ключами управляйте в профиле.

Статусы и ошибки

Ошибки FastAPI возвращаются как {"detail":"…"}; validation detail для 422 может быть структурированным списком.

Безопасность, сроки и лимиты

• Ключ хранится сервером только как keyed hash; plaintext показывается один раз после создания.
• Не кладите ключи в URL, query string, логи, frontend-код или репозиторий. Передавайте только в Authorization header.
• Для ротации создайте новый ключ, переключите клиента, затем отзовите старый в профиле. Активные ключи сейчас создаются без срока действия.
• Отчёты доступны 168 ч. с момента создания и затем исключаются из выдачи; физическое удаление выполняет периодический cleanup.
• Незавершённые pending-поиски cleanup удаляет после 24 ч. Сессия кабинета и email verification имеют отдельные настраиваемые TTL.
• Per-user лимиты: 60 общих запросов/мин и отдельные 10 create+confirm/мин. Costly запросы не расходуют общий bucket. При 429 используйте Retry-After.
• Остальные лимиты API: pagination limit до 100, offset до 100000, query до 512 символов, Idempotency-Key до 120.

English quick start

Register, verify your email, sign in, and create an API key in Profile → API keys. The plaintext token is shown once. Authenticate with Authorization: Bearer …. Create a search, confirm it with a unique Idempotency-Key, then fetch the returned report. Reports are retained for 168 hours. See Swagger UI for request and response schemas.