Internal API Reference

These endpoints are used for operating and managing the platform. They require admin access or are triggered by internal systems.

Base URL: https://rankfabric-edge.grocerybundles.workers.dev

---

Workflows

Trigger Workflow

POST /api/admin/workflow/:type

Types: domain-onboard, url-classify, keyword-classify, domain-classify, serp-tracking, app-details, asset-onboard, subscription-dispatch, crawl-run

Request (domain-onboard):

{
  "domain": "example.com",
  "project_id": "proj_abc123"
}

Response:

{
  "success": true,
  "workflow_id": "wf_xyz789",
  "status": "running"
}

Get Workflow Status

GET /api/admin/workflow/:type/:workflow_id

Response:

{
  "id": "wf_xyz789",
  "status": "running",
  "steps": [
    {"name": "fetch-backlinks", "status": "completed"},
    {"name": "classify-urls", "status": "running"}
  ],
  "output": null
}

Workflow Management

POST /api/admin/workflow/:type/:id/pause
POST /api/admin/workflow/:type/:id/resume
DELETE /api/admin/workflow/:type/:id

List Workflows

GET /api/admin/workflows/running
GET /api/admin/workflows/history
GET /api/admin/workflows/failures

---

Queue Management

Queue Status

GET /api/admin/queue-status

Response:

{
  "queues": [
    {
      "name": "backlink-classify",
      "messages": 150,
      "consumers": 1
    },
    {
      "name": "keyword-classify",
      "messages": 42,
      "consumers": 1
    }
  ]
}

Purge Queue

POST /api/admin/queue/:name/purge

---

Classification

Classify URL

POST /api/admin/classifier/classify

Request:

{
  "url": "https://example.com/blog/seo-tips",
  "use_workflow": true
}

Response:

{
  "url": "https://example.com/blog/seo-tips",
  "classification": {
    "tier1_type": "media",
    "content_type": "blog_post",
    "topic": "seo",
    "confidence": 0.87
  },
  "stages_completed": ["rules", "vectorize", "content", "llm"],
  "cost": 0.0012
}

Classify Keyword

POST /api/admin/classify-keyword

Request:

{
  "keyword": "best seo tools 2025",
  "use_workflow": true
}

Response:

{
  "keyword": "best seo tools 2025",
  "classification": {
    "journey": "consideration",
    "type": "product",
    "branded": false,
    "modifiers": ["time_sensitive"],
    "confidence": 0.92
  }
}

Classify Domain

POST /api/admin/classifier/domain

Request:

{
  "domain": "techcrunch.com",
  "use_workflow": true
}

---

Domain Operations

Domain Onboard

POST /api/admin/domains/onboard

Request:

{
  "domain": "example.com",
  "project_id": "proj_abc123",
  "options": {
    "backlinks_limit": 100,
    "keywords_limit": 500
  }
}

Recategorize Domain

POST /taxonomy/re-categorize

Request:

{
  "project_id": "proj_abc123",
  "domain": "example.com"
}

---

Bulk Operations

Bulk Save Keywords

Requires JWT authentication (internal use).

POST /keywords/bulk_save

Request:

{
  "project_id": "proj_abc123",
  "keywords": ["seo tools", "keyword research", "backlink checker"],
  "source": "ui",
  "parent_seed": "kw_parent123"
}

Response:

{
  "saved": 3
}

---

Cost Tracking

Get Costs Summary

GET /api/admin/costs

Response:

{
  "summary": {
    "dataforseo": 45.23,
    "llm": 12.50,
    "vectorize": 0.85
  },
  "period": "2025-12"
}

Get Costs by Project

GET /api/admin/costs/by-project

Get Daily Costs

GET /api/admin/costs/daily

---

App Store Operations

Trigger Taxonomy Crawl

POST /api/admin/taxonomy-crawl

Request:

{
  "platform": "apple",
  "category_ids": [6014, 6016]
}

App Store Grouping

POST /api/app-store/grouping

---

DataForSEO Operations

Check Task Status

GET /api/admin/dataforseo/tasks/:task_id

Debug DataForSEO

POST /debug/dataforseo

---

Database Operations

Debug Schema

GET /api/debug/schema

Response:

{
  "tables": [
    {"name": "domains", "columns": 15},
    {"name": "keywords", "columns": 20},
    {"name": "urls", "columns": 18}
  ]
}

Run Migration

POST /api/admin/migrate

---

Diagnostics

Health Check

GET /health

ClickHouse Status

GET /test/clickhouse

Initialize ClickHouse

POST /init/clickhouse

Keyword Diagnostics

GET /diagnostics/keyword?keyword=test

---

Cron Jobs

Subscription Dispatch (Daily)

Triggered automatically at 2 AM UTC, or manually:

POST /api/admin/workflow/subscription-dispatch

Request:

{
  "dry_run": false,
  "project_id": "proj_abc123",
  "limit": 1000
}

---

Authentication Notes

Endpoint Pattern	Auth Type
/api/*	API Key (Bearer or query)
/api/admin/*	API Key
/keywords/bulk_save	JWT (BASE44_JWT_SECRET)
/generate-taxonomy	JWT
/taxonomy/*	JWT
/api/public/*	None
/*webhook*	None (webhook signature)

---

Internal Queues

Queue	Binding	Purpose
rankfabric-tasks-v2	QUEUE	General task queue
backlink-classify	BACKLINK_CLASSIFY_QUEUE	URL classification
keyword-classify	KEYWORD_CLASSIFY_QUEUE	Keyword classification
domain-classify	DOMAIN_CLASSIFY_QUEUE	Domain classification
domain-onboard	DOMAIN_ONBOARD_QUEUE	Domain onboarding
llm-verification	LLM_VERIFY_QUEUE	LLM re-verification
app-info-fetch	APP_INFO_QUEUE	App metadata
app-keyword-search	APP_KEYWORD_QUEUE	App keyword search
dlq	DLQ	Dead letter queue