IF
IndexFlowing / Docs
🌐 切换中文文档 GitHub ↗

HTTP & REST API Reference

IndexFlow exposes a unified REST API under /api and /api/v1.

Authentication

All protected endpoints require an if_token cookie containing a valid HMAC-SHA256 signed JWT:

Cookie: if_token=<YOUR_JWT_TOKEN>

1. System & Health

Health Check

  • Method & Route: GET /health
  • Authentication: None (Public)
  • Response: 200 OK
{
  "db": "sqlite-wal",
  "service": "indexflow-core",
  "status": "healthy"
}

2. Dashboard & Statistics

Get Site Metrics

  • Method & Route: GET /api/v1/stats
  • Query Parameters:
    • site_id (optional, integer): ID of target site (defaults to 1).
  • Response: 200 OK
{
  "url_total": 1250,
  "google_indexed": 850,
  "google_crawled_not_indexed": 40,
  "google_discovered_not_indexed": 120,
  "google_not_indexed": 160,
  "google_uninspected": 240,
  "bing_indexed": 920,
  "bing_not_indexed": 180,
  "bing_failed": 0,
  "bing_uninspected": 150,
  "seo_passed": 1200,
  "seo_issues": 50,
  "seo_warnings": 110,
  "pending_submit": 210,
  "gsc_used_24h": 45,
  "last_seo_scan_at": "2026-03-30T10:15:00Z"
}

3. Pipeline Lifecycle Management

Supported pipeline stages:

  • sitemap: Sitemap asset discovery.
  • seo-gate: Technical SEO & GEO pre-flight quality gate.
  • gsc-inspect: Google Search Console inspection.
  • bing-inspect: Bing Webmaster inspection.
  • push-submit: Active search engine submission.

Start Pipeline Stage

  • Method & Route: POST /api/v1/pipeline/{stage}/start
  • Query Parameters:
    • site_id (optional, integer): ID of target site (defaults to 1).
  • Response: 200 OK (Returns updated HTML partial for HTMX, triggers refreshTable header).

Stop Pipeline Stage

  • Method & Route: POST /api/v1/pipeline/{stage}/stop
  • Query Parameters:
    • site_id (optional, integer): ID of target site (defaults to 1).
  • Response: 200 OK

Sync GSC Search Analytics Pool (0-Quota)

  • Method & Route: POST /api/v1/pipeline/gsc-inspect/sync
  • Query Parameters:
    • site_id (optional, integer): ID of target site.
  • Response: 204 No Content

4. URL Inspection & Audits

Inspect Single URL

  • Method & Route: POST /api/v1/urls/{id}/inspect
  • Path Parameters:
    • id (required, integer): Primary key of the URL.
  • Query Parameters:
    • engine (required, string): seo | google | gsc | bing
  • Response: 200 OK (Returns updated drawer modal HTML).

Batch Inspect URLs

  • Method & Route: POST /api/v1/urls/batch-inspect
  • Request Headers: Content-Type: application/json
  • Request Body:
{
  "selected_ids": [101, 102, 103],
  "engine": "seo"
}
  • Response: 200 OK
{
  "success": true,
  "processed_count": 3,
  "rechecked_count": 3
}

5. Active Search Engine Submissions

Submit Single URL

  • Method & Route: POST /api/v1/urls/{id}/submit
  • Path Parameters:
    • id (required, integer): Primary key of the URL.
  • Query Parameters:
    • provider (required, string): bing | google
  • Response: 200 OK

Batch Submit URLs

  • Method & Route: POST /api/v1/urls/batch-submit
  • Request Headers: Content-Type: application/json
  • Request Body:
{
  "selected_ids": [101, 102, 103],
  "provider": "bing"
}
  • Response: 200 OK
{
  "success": true,
  "submitted_count": 3
}

6. Monitoring & Watchlist

Toggle URL Watch Status

  • Method & Route: POST /api/v1/monitoring/{id}/watch
  • Path Parameters:
    • id (required, integer): Primary key of the URL.
  • Request Body:
{
  "watched": true
}
  • Response: 200 OK
{
  "success": true
}

Batch Watch / Unwatch URLs

  • Method & Route: POST /api/v1/monitoring/batch-watch
  • Request Body:
{
  "selected_ids": [101, 102, 103],
  "watched": true
}
  • Response: 200 OK
{
  "success": true,
  "updated_count": 3
}

7. Site Credentials Testing

Test Google Service Account Connection

  • Method & Route: POST /api/v1/sites/test-google
  • Request Body:
{
  "service_account_json": "{\"type\":\"service_account\",\"project_id\":\"...\",...}",
  "domain": "example.com"
}
  • Response: 200 OK
{
  "ok": true,
  "message": "验证成功，已识别到站点: sc-domain:example.com"
}

Test Bing Webmaster API Key

  • Method & Route: POST /api/v1/sites/test-bing-webmaster
  • Request Body:
{
  "bing_webmaster_api_key": "32_HEX_CHARACTER_KEY",
  "domain": "example.com"
}
  • Response: 200 OK
{
  "ok": true,
  "message": "验证成功，识别到 1 个可访问站点"
}

Test Bing IndexNow Key File

  • Method & Route: POST /api/v1/sites/test-indexnow
  • Request Body:
{
  "bing_indexnow_key": "32_HEX_CHARACTER_KEY",
  "domain": "example.com"
}
  • Response: 200 OK
{
  "ok": true,
  "message": "密钥文件验证通过"
}

8. Site Management

Delete Site

  • Method & Route: POST /api/v1/sites/{id}/delete
  • Path Parameters:
    • id (required, integer): Primary key of the site.
  • Response: 200 OK
{
  "success": true
}

Note: Deleting a site triggers cascading deletion across all associated urls, health_checks, submission_logs, and index_status_history records.

← Introduction API Reference →