API docs by Redocly

Kotopogoda Uploader API (1.4.1)

Download OpenAPI specification:

Контракт между Android-приложением и бэкендом котопогода (fly.io). Запросы (кроме /v1/health и /v1/devices/attach) подписываются HMAC.

Health

Health

Returns the current status of the API and its dependencies.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "now": "2019-08-24T14:15:22Z",
  • "db": "ok",
  • "queue": "ok",
  • "telegram": "ok"
}

Devices

Pair device by one-time token

Accepts normalized pairing tokens consisting of 6–8 uppercase characters in the range A-Z and digits 2-9. Clients should strip any prefixes or deep-link wrappers before invoking this endpoint.

Request Body schema: application/json
required
One of
token
required
string [ 6 .. 8 ] characters ^[A-Z2-9]{6,8}$

Pairing payload captured from QR scan or manual entry.

code
string [ 6 .. 8 ] characters ^[A-Z2-9]{6,8}$
Deprecated

Legacy alias for token; accepts the same payloads until decommission.

Responses

Request samples

Content type
application/json
Example
{
  • "token": "BCDF29"
}

Response samples

Content type
application/json
Example
{
  • "device_id": "8e0a8d9c-2b62-4f12-9ad9-1234567890ab",
  • "device_secret": "shh-keep-me",
  • "id": "8e0a8d9c-2b62-4f12-9ad9-1234567890ab",
  • "secret": "shh-keep-me"
}

Revoke current device

Invalidates the currently paired device secret and revokes access.

Authorizations:
hmacSig

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Uploads

Upload photo (stream) with idempotency

Accepts photo uploads with metadata while enforcing idempotent retries.

Authorizations:
hmacSig
header Parameters
X-Device-Id
required
string <uuid>
X-Timestamp
required
string <date-time>

RFC3339. Окно валидности ±300 сек.

X-Nonce
required
string <uuid>

Одноразовый идентификатор запроса (anti-replay).

X-Content-SHA256
required
string

Hex SHA-256 тела запроса (для multipart — самого файла).

Idempotency-Key
required
string

Обычно равен content_sha256; повторный запрос возвращает тот же результат.

Request Body schema: multipart/form-data
required
file
required
string <binary>
content_sha256
required
string

Hex SHA-256 of the file (must equal X-Content-SHA256)

mime
required
string
size
required
integer <int64>
exif_date
integer <int64>

Epoch millis (optional)

original_relpath
string

Relative path inside selected SAF root (optional)

Responses

Response samples

Content type
application/json
{
  • "upload_id": "string",
  • "status": "accepted"
}

Upload processing status

Возвращает текущее состояние обработки ранее загруженного файла. Поле status отражает этап жизненного цикла (queued, processing, done, failed), а временные метки позволяют отслеживать прогресс. Пока загрузка не завершена, в ответ добавляется заголовок Retry-After с рекомендацией, через сколько секунд повторить запрос статуса.

Authorizations:
hmacSig
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "queued",
  • "processed": true,
  • "error": "string",
  • "failure_reason": "string",
  • "queued_at": "2019-08-24T14:15:22Z",
  • "processing_started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z"
}