GeoPass Developer Portal

This page documents the REST API that powers the official GeoPass web app at geopass.ge, operated by Individual Entrepreneur Bakur Jobava. It is published so agents and developers can understand the API surface automatically. GeoPass does not yet offer a self-service third-party API program (no public API key self-signup or sandbox environment) - if you want to integrate as a partner, contact us first.

When to use this API

Reach for this API if you are building a tool that needs to: generate or fetch a Georgian-citizenship exam practice paper, grade submitted answers, or check a GeoPass user's subscription status on their behalf, with their authorization. It is not a general-purpose trivia or quiz API, and it is not intended for scraping question content in bulk.

Base URL

https://api.geopass.ge

API reference

OpenAPI spec (JSON): https://api.geopass.ge/openapi.json (also mirrored at /openapi.json on this domain)
Interactive Swagger UI: https://api.geopass.ge/docs

Authentication

Most endpoints require a JSON Web Token obtained from POST /api/auth/login, POST /api/auth/google, or refreshed via POST /api/auth/refresh. Send it as:

Authorization: Bearer <token>

/api/auth/**, /api/flitt/**, and /redirect/flitt/** are public; everything else requires a valid token, and topic/subtopic/question content additionally requires an active subscription or admin role.

Error format

Every error response is JSON, never an HTML page, with a stable code, a human-readable message, and a resolution hint, for example:

{
  "timestamp": "2026-10-29T12:00:00",
  "status": 404,
  "error": "Not Found",
  "message": "No endpoint exists at this path.",
  "code": "NOT_FOUND",
  "resolution": "See the API documentation at https://api.geopass.ge/docs or the OpenAPI spec at https://api.geopass.ge/openapi.json.",
  "path": "/api/does-not-exist"
}

Rate limits

Requests are limited per client IP address. Every response includes RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers (seconds until the window resets) so callers can self-throttle. Exceeding the limit returns 429 Too Many Requests with a Retry-After header and a JSON error body.

CLI / SDKs

There is no official CLI tool or client SDK published yet. The OpenAPI spec above can be used to generate a client in most languages in the meantime.