Projects API

In Rankion a project is the central container — one domain per project, one team owner, and all sub-resources (articles, keywords, internal link maps, storylines) hang off it. Alongside this there are tracking projects as their own resource for AI visibility monitoring (see below).

CRUD

# List
curl -H "Authorization: Bearer $TOKEN" "$BASE/projects"

# Create
curl -X POST "$BASE/projects" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"My Blog","domain":"myblog.com","language":"en","country":"US"}'

Response (truncated):

{
  "data": {
    "id": 12,
    "name": "My Blog",
    "domain": "myblog.com",
    "language": "en",
    "country": "US",
    "team_id": 7,
    "created_at": "2026-05-01T08:30:00Z"
  }
}

language sets the project's content language: allowed values are de, en, fr, es, and pl. country is the target country code; in the project form it's a dropdown that now includes Poland (PL).

Project-scoped sub-resources

Articles

All article-related CRUD and generation endpoints attach to the project:

Full article API → Articles API.

Keywords

Internal linking

Other project sub-resources

Tracking projects (their own resource!)

Tracking projects are separate from regular projects. They are the data foundation for AI Visibility Tracking — one brand per tracking project, one set of keywords, one set of platforms.

Endpoint namespace: /v1/tracking-projects/...

Wizard flow

The web UI has a 5-step wizard you can replicate 1:1 over the API:

# Step 1+2: start analysis
RESP=$(curl -s -X POST "$BASE/tracking-projects/analyze" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"mode":"domain","domain":"example.com","language":"en","country":"US"}')
PID=$(echo $RESP | jq -r .project_id)

# Step 3+4: poll until completed
while [ "$(curl -s "$BASE/tracking-projects/$PID/analysis-status" \
  -H "Authorization: Bearer $TOKEN" | jq -r .analysis_status)" != "completed" ]; do
  sleep 3
done

# Step 5: atomic activate
curl -X POST "$BASE/tracking-projects/$PID/activate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "keywords":["best crm","crm software"],
    "competitors":[{"domain":"hubspot.com"}],
    "prompts":[{"prompt":"What is the best CRM?","category":"recommendation"}],
    "platforms":["chatgpt","perplexity"],
    "frequency":"weekly",
    "with_search":true,
    "reality_check_enabled":true
  }'

Runtime operations

The complete table of all ~30 tracking endpoints lives in docs/API_REFERENCE.md.

Example workflow: project + first article

# 1) Create project
PID=$(curl -s -X POST "$BASE/projects" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Demo Site","domain":"demo.example","language":"en","country":"US"}' \
  | jq -r .data.id)

# 2) Create article stub
ART=$(curl -s -X POST "$BASE/projects/$PID/articles" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Best AI Tools 2026","status":"draft"}' \
  | jq -r .data.id)

# 3) Generate article content (5 credits, async)
curl -X POST "$BASE/articles/$ART/generate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"keyword":"AI tools 2026","article_type":"blog","target_length":1500}'

# 4) Poll until ready
while [ "$(curl -s "$BASE/articles/$ART" \
  -H "Authorization: Bearer $TOKEN" | jq -r .data.processing_status)" != "ready" ]; do
  sleep 5
done

Detailed workflows for articles: Articles API.

Related: Authentication & API Tokens · Credits & Rate Limits · AI Visibility Tracking.