API Reference¶

This document lists the currently implemented HTTP API in the Flask backend.

Base URL¶

• Development: http://localhost:5000/api
• Production: https://<your-domain>/api

Auth Model¶

• Cookie-based Flask session auth is used.
• Public endpoints: POST /auth/register, POST /auth/login
• All other endpoints require a logged-in app user.
• Most data endpoints are scoped by active Instagram account and accept either:
• profile_id=<instagram_user_id>
• instagram_user_id=<instagram_user_id>

Error Format¶

All API errors return JSON:

{
  "error": "Description"
}

Common status codes: 200, 201, 202, 400, 401, 404, 409, 502.

Auth Endpoints (/api/auth)¶

POST /auth/register¶

Create app user.

Request:

{
  "name": "alice",
  "password": "secret"
}

Response 201:

{
  "app_user_id": "app_...",
  "name": "alice"
}

POST /auth/login¶

Log in app user and return profile context.

Response 200:

{
  "app_user_id": "app_...",
  "name": "alice",
  "instagram_users": [
    {
      "instagram_user_id": "123456",
      "name": "Primary IG",
      "username": "alice_ig",
      "created_at": "2026-03-20T10:30:00",
      "credentials_old": false,
      "credentials_age_hours": 4
    }
  ],
  "active_instagram_user": {
    "instagram_user_id": "123456",
    "name": "Primary IG",
    "username": "alice_ig",
    "created_at": "2026-03-20T10:30:00",
    "credentials_old": false,
    "credentials_age_hours": 4
  }
}

Note: credential fields (session_id, csrf_token, password_hash) are never returned.

POST /auth/logout¶

Clear session.

Response 200:

{
  "ok": true
}

GET /auth/me¶

Get current app-user context.

Response 200 (not logged in):

null

GET /auth/instagram-api-usage¶

Get grouped API/caching usage summary.

Optional query:

• instagram_user_id

GET /auth/instagram-users¶

List Instagram accounts for current app user (sanitized payload).

POST /auth/instagram-users¶

Create Instagram account for current app user.

Request:

{
  "name": "Primary IG",
  "csrf_token": "...",
  "session_id": "...",
  "user_id": "123456"
}

Response 201:

{
  "instagram_user": {
    "instagram_user_id": "123456",
    "name": "Primary IG",
    "username": "alice_ig",
    "created_at": "2026-03-20T10:30:00",
    "credentials_old": false,
    "credentials_age_hours": 0
  },
  "me": {
    "app_user_id": "app_...",
    "name": "alice",
    "instagram_users": [],
    "active_instagram_user": null
  }
}

GET /auth/instagram-users/<instagram_user_id>¶

Get one Instagram account (sanitized payload).

PATCH /auth/instagram-users/<instagram_user_id>¶

Update account display name and/or credentials via cookie string.

Request:

{
  "display_name": "Updated Name",
  "cookie_string": "sessionid=...; ds_user_id=...; csrftoken=..."
}

POST /auth/instagram-users/<instagram_user_id>/select¶

Set active Instagram account.

DELETE /auth/instagram-users/<instagram_user_id>¶

Delete one Instagram account and associated data scope.

DELETE /auth/instagram-users¶

Delete all Instagram accounts for current app user.

Scan & History Endpoints (/api)¶

POST /scan¶

Start async follower scan.

GET /scan/status¶

Get scan status (idle | running | cancelled | error) and last scan metadata.

POST /scan/cancel¶

Mark running scan as cancelled.

GET /summary¶

Get latest scan summary (or null if no scan yet).

GET /history¶

Get scan history.

Query options:

• range=recent|all_time
• days
• limit
• offset

GET /scan-analytics¶

Get day-bucketed analytics for recent scan deltas.

Query options:

• days (default 30)

GET /diff/latest¶

Get latest computed diff.

GET /diff/<diff_id>¶

Get a specific diff by ID.

Image Endpoint (/api)¶

GET /image/<pk_id>¶

Serve cached profile image or queue download and return placeholder.

• pk_id must be numeric.
• Returns image bytes (image/jpeg) when successful.

Prediction Endpoints (/api)¶

POST /predictions/follow-back¶

Create or refresh a follow-back prediction.

Request fields:

• username or user_id
• refresh (optional)
• force_background (optional)
• relationship_type (followers|following, optional)
• prediction_session_id (optional)

Returns 200 for immediate result or 202 when background task is queued.

GET /targets/<target_profile_id>/relationship-cache¶

Get relationship cache status for a target.

Optional query:

• sync_counts=true|false

POST /targets/<target_profile_id>/relationship-cache/refresh¶

Refresh one relationship cache (followers or following) in background.

GET /predictions/history¶

List prediction sessions/history.

Query options:

• target_profile_id
• limit (max 200)
• offset

GET /predictions/history/sessions/<prediction_session_id>¶

List predictions in one session.

GET /predictions/<prediction_id>¶

Get prediction record, linked task status, and assessments.

PATCH /predictions/<prediction_id>/feedback¶

Store feedback/assessment.

Request fields include:

• assessment_status: correct|wrong|pending_review|ignored
• notes
• observed_at
• expected_direction: higher|lower
• expected_value: 0.0..1.0

GET /prediction-tasks/<task_id>/status¶

Get one prediction task status.

GET /prediction-tasks/latest¶

Get latest prediction task for current scope.

Optional query:

• target_profile_id

POST /prediction-tasks/<task_id>/cancel¶

Cancel queued/running prediction task.

Tasks Endpoint (/api)¶

GET /tasks¶

Unified live task list combining:

• prediction tasks
• scan tasks
• automation actions

Cancelled tasks are retained briefly for UI visibility.

Automation Endpoints (/api/automation)¶

GET /automation/cache-efficiency¶

Get read-cache hit/call efficiency summary per category.

GET /automation/cache-size¶

Get cache scope disk stats.

GET /automation/following-users¶

Get current following list enriched with follows-you and count metadata.

POST /automation/batch-follow/prepare¶

Stage intelligent batch-follow action.

POST /automation/batch-unfollow/prepare¶

Stage batch-unfollow action.

POST /automation/left-right-compare/prepare¶

Stage left-right comparison action.

POST /automation/actions/<action_id>/confirm¶

Queue staged automation action for execution.

POST /automation/actions/<action_id>/cancel¶

Cancel automation action.

GET /automation/actions/<action_id>¶

Get action details with items_by_status.

GET /automation/actions¶

List actions for current scope.

Query options:

• action_type
• limit (max 500)

GET /automation/safelists/<list_type>¶

Get safelist entries.

list_type values:

• do_not_follow
• never_unfollow

POST /automation/safelists/<list_type>¶

Add entries to safelist.

Request:

{
  "entries": ["@user1", "https://instagram.com/user2"]
}

DELETE /automation/safelists/<list_type>/<identity_key>¶

Delete one safelist entry.

GET /automation/alternative-account-links¶

List alternative-account links.

Optional query:

• primary_identity_key

POST /automation/alternative-account-links¶

Add primary-to-alternative account links.

Request:

{
  "primary_account": "@primary",
  "alternative_accounts": ["@alt1", "@alt2"],
  "linkedin_accounts": ["https://linkedin.com/in/..."],
  "trigger_discovery": true
}

DELETE /automation/alternative-account-links/<primary_identity_key>/<alt_identity_key>¶

Delete one alternative-account link.

Minimal Example Flow¶

# 1) login
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"name":"alice","password":"secret"}'

# 2) select active IG account
curl -X POST http://localhost:5000/api/auth/instagram-users/123456/select

# 3) start scan
curl -X POST "http://localhost:5000/api/scan?profile_id=123456"

# 4) poll status
curl "http://localhost:5000/api/scan/status?profile_id=123456"

# 5) read latest diff
curl "http://localhost:5000/api/diff/latest?profile_id=123456"

Next: Backend API, Architecture