Gericos BInformed — API documentation

1) Authentication

Authentication uses a short-lived JWT access token and a rotating refresh token. Emails are case-normalized (lowercase/trim).

POST /v1/auth/signup

Create a new account.

curl -X POST https://api-binformed.gericos.com/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"your-password"}'

POST /v1/auth/login

Returns an access token, a refresh_token and the user api_key.

curl -s -X POST https://api-binformed.gericos.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"your-password"}'
# Response:
# {
#   "token": "<JWT access token>",
#   "refresh_token": "<opaque refresh token>",
#   "refresh_expires_at": 1739999999,
#   "api_key": "<per-user API key>"
# }

POST /v1/auth/refresh

Rotates the refresh token and returns a new access token + refresh token.

curl -s -X POST https://api-binformed.gericos.com/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"<your-refresh-token>"}'

POST /v1/auth/logout

Revokes all active refresh tokens for the current user.

curl -s -X POST https://api-binformed.gericos.com/v1/auth/logout \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{}'

2) Devices

Register / unregister a device (Android/iOS) with the user’s account.

POST /v1/devices/register

curl -s -X POST https://api-binformed.gericos.com/v1/devices/register \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"platform":"android","fcm_token":"<FCM or APNS token>","app_version":"1.0"}'

POST /v1/devices/unregister

Unregister a specific token or all tokens for the user.

# Unregister a specific device
curl -s -X POST https://api-binformed.gericos.com/v1/devices/unregister \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"fcm_token":"<FCM token>"}'

# Unregister ALL devices for the user
curl -s -X POST https://api-binformed.gericos.com/v1/devices/unregister \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"all": true}'

GET /v1/devices

curl -s -X GET https://api-binformed.gericos.com/v1/devices \
  -H "Authorization: Bearer <JWT>"

3) Send notifications

Server-to-server notifications use the per-user API key via header X-API-Key. The body can include a title, message and optional URL.

POST /v1/notify

curl -s -X POST https://api-binformed.gericos.com/v1/notify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{
        "title":"Build finished",
        "message":"CI completed successfully",
        "url":"https://example.com/build/123"
      }'

On mobile, each push is saved locally and shown in the in-app feed (and as a system notification).

4) Messages history

Fetch last messages (default 30 days, up to 90). Requires a valid JWT.

GET /v1/messages?days=30

curl -s -X GET 'https://api-binformed.gericos.com/v1/messages?days=30' \
  -H "Authorization: Bearer <JWT>"
# Response:
# { "items": [
#   { "title":"...", "body":"...", "url":null, "ts": 1734000000000 },
#   ...
# ] }

5) Account export & deletion

GET /v1/me/export

Export your data (JSON). Use JWT authentication.

curl -L -X GET https://api-binformed.gericos.com/v1/me/export \
  -H "Authorization: Bearer <JWT>" -o export.json

GET /v1/me/export?format=zip

Export as a ZIP containing JSON + CSV per collection.

curl -L -X GET 'https://api-binformed.gericos.com/v1/me/export?format=zip' \
  -H "Authorization: Bearer <JWT>" -o export.zip

DELETE /v1/me/delete

Delete the account and associated data (irreversible).

curl -X DELETE https://api-binformed.gericos.com/v1/me/delete \
  -H "Authorization: Bearer <JWT>"

6) Errors & common responses

Errors are returned as JSON with an error field and HTTP status codes:

• 400 — missing/invalid parameters
• 401 — invalid/expired token (try /v1/auth/refresh)
• 403 — forbidden
• 404 — not found
• 409 — conflict (e.g. email already exists)
• 429 — rate limited
• 500 — server error

{ "error": "invalid_credentials" }

7) Security notes

• Use HTTPS only.
• JWT access tokens are short-lived; use /v1/auth/refresh for silent renewal.
• Refresh tokens are opaque, stored hashed and rotated at each refresh.
• API keys are per-user; keep them secret. Regenerate if compromised.
• Rate limiting is enabled; configure Express trust proxy if running behind a proxy.