REST API v1 All endpoints + code examples →

API Reference

This page is the developer reference for the REST API v1: 400+ endpoints, bearer-token authentication and programmatic access to every feature.

Integrate AI content generation, SEO analysis, keyword research, and content management into your applications. Authenticate with bearer tokens via Laravel Sanctum.

# Quick Start curl -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json" \ https://rankion.ai/api/v1/team

Start free — API in the Free plan All endpoints with code examples (cURL · Python · PHP · JavaScript)

Connect in 60 seconds

One Sanctum token, three ways in. Everything is included in every plan — even the free plan with 50 credits.

MCP-Server

Every endpoint becomes a typed tool for Claude & AI agents.

https://rankion.ai/mcp

Claude-Skill

A single markdown file that Claude Code loads natively.

https://rankion.ai/claude-skill

OpenAPI-Spec

Machine-readable for n8n, Zapier, the ChatGPT connector, and your own agents.

/api/v1/openapi.yaml ↓

# 1) Token holen: Dashboard → Einstellungen → API Tokens # 2) MCP-Server in Claude Code verbinden claude mcp add rankion --transport http https://rankion.ai/mcp \ --header "Authorization: Bearer rk_live_..." # 3) Oder direkt per REST testen (Free-Plan reicht) curl -H "Authorization: Bearer rk_live_..." https://rankion.ai/api/v1/team

Authentication

All API requests require a bearer token. Create your token under Settings → API Tokens in the dashboard.

# Jeden Request mit Bearer Token authentifizieren curl -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ https://rankion.ai/api/v1/team

Note: Send Accept: application/json with every request, and additionally Content-Type: application/json for POST/PUT requests.

Errors & status codes

Code	Meaning
`200`	Success
`201`	Resource created
`202`	Accepted – background processing started
`204`	Deleted (no content)
`401`	Not authenticated – invalid token
`402`	Insufficient credits
`403`	No permission for this resource
`404`	Resource not found
`422`	Validation error – check the parameters
`429`	Rate limit reached
`500`	Server error

Credit system

Some endpoints consume credits. Usage is checked before execution. If your balance is insufficient, you'll receive a 402 error.

Endpoint	Credits
AI Scanner – Detection	2 Credits
AI Scanner – Humanization	4+ Credits
Keyword research	5 Credits
Image generation	5 Credits
Content Audit	10 Credits
Article generation	10+ Credits
Bulk Generation	4 / article
Competitor analysis	20 Credits

Team

Retrieve information about your current team.

GET /v1/team

Returns team info with plan, credits, and statistics.

// Response 200 { "id": 1, "name": "Mein Team", "plan": "pro", "credit_balance": 5000, "members_count": 3, "projects_count": 5, "articles_count": 120 }

Projects

Manage projects. Each project has its own domain, language, and brand voice.

GET /v1/projects

List all of the team's projects with brand voice.

GET /v1/projects/{project}

Single project with brand voice and the last 10 articles.

POST /v1/projects

Create a new project.

Parameter	Type	Info
`name`	string	Required Project name
`domain`	string	Optional Website URL
`language`	string	Optional de, en, es, fr (default: de)
`description`	string	Optional Project description

# Beispiel curl -X POST https://rankion.ai/api/v1/projects \ -H "Authorization: Bearer TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"Mein Blog","domain":"https://blog.example.com","language":"de"}'

PUT /v1/projects/{project}

Update a project. Same parameters as POST (all optional).

DEL /v1/projects/{project}

Delete the project and all associated data. Not reversible.

Articles

Manage, score, optimize, and check the freshness of articles.

GET /v1/projects/{project}/articles

Paginated list of a project's articles (20 per page).

GET /v1/articles/{article}

Retrieve a single article with all details (content, scores, metadata).

POST /v1/projects/{project}/articles

Create a new article manually (not generated).

Parameter	Type	Info
`title`	string	Required
`content`	string	Required HTML content
`target_keyword`	string	Optional
`language`	string	Optional de, en, es, fr
`status`	string	Optional draft, published

PUT /v1/articles/{article}

Update an article (title, content, status, meta_title, meta_description, target_keyword).

DEL /v1/articles/{article}

Delete an article.

POST /v1/articles/{article}/score

Start SEO scoring as a background process. Returns 202 Accepted.

POST /v1/articles/{article}/optimize

Start content optimization based on a URL.

Parameter	Type	Info
`url`	string	Required URL of the existing article

GET /v1/articles/{article}/freshness

Check content freshness: age, score, status (fresh/aging/stale/critical).

GET /v1/articles/{article}/link-suggestions

Retrieve internal linking suggestions for an article.

Keywords

Manage keywords and run AI-based keyword research.

GET /v1/projects/{project}/keywords

Paginated list of a project's keywords.

POST /v1/projects/{project}/keywords

Add a keyword.

Parameter	Type	Info
`keyword`	string	Required min. 2 characters
`search_volume`	integer	Optional
`difficulty`	integer	Optional 0-100
`language`	string	Optional de, en, es, fr

DEL /v1/keywords/{keyword}

Delete a keyword.

POST /v1/keywords/research 5 Credits

AI-based keyword research with search volume and difficulty.

Parameter	Type	Info
`keyword`	string	Required min. 2 characters
`language`	string	Optional de, en, es, fr
`country`	string	Optional Country code (default: de)

# Beispiel curl -X POST https://rankion.ai/api/v1/keywords/research \ -H "Authorization: Bearer TOKEN" \ -H "Content-Type: application/json" \ -d '{"keyword":"seo optimierung","language":"de"}'

Images

Manage generated images.

GET /v1/projects/{project}/images

List all images of a project.

GET /v1/images/{image}

Retrieve a single image with metadata.

DEL /v1/images/{image}

Delete an image.

Style Profiles

Create and manage writing style profiles for consistent content.

GET /v1/projects/{project}/style-profiles

All style profiles of a project.

POST /v1/projects/{project}/style-profiles

Create a style profile.

Parameter	Type	Info
`name`	string	Required
`tone`	string	Optional e.g. professional, casual, academic
`writing_style`	string	Optional
`vocabulary_level`	string	Optional
`sentence_structure`	string	Optional
`rules`	object	Optional Custom rules

PUT /v1/style-profiles/{styleProfile}

Update a style profile.

DEL /v1/style-profiles/{styleProfile}

Delete a style profile.

Knowledge Base

Upload knowledge documents that are used as context during content generation.

GET /v1/projects/{project}/knowledge-base

List all documents in the knowledge base.

POST /v1/projects/{project}/knowledge-base

Create a new knowledge document.

Parameter	Type	Info
`title`	string	Required
`content`	string	Required Text content
`type`	string	Optional text, url, pdf

DEL /v1/knowledge-base/{knowledgeDocument}

Delete a knowledge document.

Link Lists

Link lists for internal and external linking in generated articles.

GET /v1/projects/{project}/link-lists

All link lists of a project.

POST /v1/projects/{project}/link-lists

Create a link list.

Parameter	Type	Info
`name`	string	Required
`links`	array	Required Array of {url, anchor_text, description}

DEL /v1/link-lists/{linkList}

Delete a link list.

Goals

Define content goals that are taken into account during generation.

GET /v1/goals

List all goals (system + custom).

POST /v1/goals

Create a custom goal.

Parameter	Type	Info
`name`	string	Required
`description`	string	Optional
`prompt_instructions`	string	Optional AI instructions
`metrics`	object	Optional Metrics

DEL /v1/goals/{goal}

Delete a custom goal (system goals are protected).

Editorial calendar

Manage the editorial calendar for content planning.

GET /v1/projects/{project}/calendar

List calendar entries. Optionally filter with ?from=2026-01-01&to=2026-03-31.

POST /v1/projects/{project}/calendar

Create a calendar entry.

Parameter	Type	Info
`title`	string	Required
`planned_date`	date	Required YYYY-MM-DD
`status`	string	Optional planned, in_progress, published
`notes`	string	Optional

PUT /v1/calendar/{entry}

Update a calendar entry.

DEL /v1/calendar/{entry}

Delete a calendar entry.

AI Scanner

Detect and humanize AI-generated text.

POST /v1/ai-scanner/detect 2 Credits

Analyze text for AI generation.

Parameter	Type	Info
`text`	string	Required min. 50 characters
`scan_type`	string	Optional quick, deep (default: quick)

// Response 200 { "score": 85, "scan_type": "quick", "word_count": 250, "details": { ... } }

POST /v1/ai-scanner/humanize 4+ Credits

Humanize an article (background process, 202 Accepted).

Parameter	Type	Info
`article_id`	integer	Required
`level`	string	Optional light, medium, aggressive

Content Audit

Automatically analyze and score website content.

GET /v1/content-audits

List all content audits of the team.

POST /v1/content-audits 10 Credits

Start a new content audit (background process).

Parameter	Type	Info
`source_url`	string	Required URL of the website to analyze
`type`	string	Optional full, quick

GET /v1/content-audits/{audit}

Retrieve a single audit with all analyzed pages.

Competitor analysis

Analyze competitors and identify content gaps.

GET /v1/competitor-analyses

List all competitor analyses.

POST /v1/competitor-analyses 20 Credits

Start a new competitor analysis.

Parameter	Type	Info
`project_id`	integer	Required
`domain`	string	Required Domain without protocol
`language`	string	Optional de, en, es, fr
`competitor_limit`	integer	Optional max. number of competitors

GET /v1/competitor-analyses/{analysis}

Retrieve the analysis result with competitors and content gaps.

AI Visibility Tracking

Monitor your domain's visibility in AI search engines (ChatGPT, Perplexity, Gemini).

GET /v1/tracking-projects

List all tracking projects with scores.

GET /v1/tracking-projects/{trackingProject}

Single tracking project with visibility history and keyword details.

POST /v1/tracking-projects/{trackingProject}/run

Start a manual tracking run (background process).

Content generation

Generate articles and images with AI.

POST /v1/generate/article 10+ Credits

Generate an AI article (background process, 202 Accepted).

Parameter	Type	Info
`project_id`	integer	Required
`keyword`	string	Required Main keyword
`type`	string	Optional blog-post, guide, listicle, review, comparison, pillar
`length`	integer	Optional 300-5000 words (default: 1500)
`tone`	string	Optional e.g. professional, casual
`language`	string	Optional de, en, es, fr

# Beispiel: Blog-Artikel generieren curl -X POST https://rankion.ai/api/v1/generate/article \ -H "Authorization: Bearer TOKEN" \ -H "Content-Type: application/json" \ -d '{ "project_id": 1, "keyword": "seo optimierung 2026", "type": "guide", "length": 2000, "language": "de" }' // Response 202 { "message": "Article generation queued", "article_id": 42 }

POST /v1/generate/image 5 Credits

Generate an AI image (background process, 202 Accepted).

Parameter	Type	Info
`project_id`	integer	Required
`prompt`	string	Required Image description
`style`	string	Optional photo, illustration, 3d, watercolor

Bulk Generation

Generate multiple articles at once.

GET /v1/bulk-generations

List all bulk generations with status.

POST /v1/bulk-generations 4 / article

Start a bulk generation.

Parameter	Type	Info
`project_id`	integer	Required
`keywords`	array	Required Array of keywords
`settings`	object	Optional {type, length, tone, language}

GET /v1/bulk-generations/{bulk}

Retrieve the status of a bulk generation with individual items.

Autopilot

Configure automatic content generation on a schedule.

GET /v1/autopilot

List all autopilot schedules.

POST /v1/autopilot

Create an autopilot schedule.

Parameter	Type	Info
`project_id`	integer	Required
`name`	string	Required
`frequency`	string	Required daily, weekly, biweekly, monthly
`keyword_source`	string	Optional manual, keyword_list, ai_suggest
`keywords`	array	Optional If manual: keyword array
`settings`	object	Optional {type, length, tone}

PUT /v1/autopilot/{schedule}

Update the schedule. Additionally: is_active (boolean) to activate/deactivate.

DEL /v1/autopilot/{schedule}

Delete the schedule.

Credits

Query credit balance and history.

GET /v1/credits

Retrieve the current balance and plan.

// Response 200 { "balance": 5000, "plan": "pro" }

GET /v1/credits/history

Paginated credit history (20 entries per page).

Blog (Admin)

Manage blog categories and posts.

Posts

GET /v1/blog/posts

List all blog posts (paginated).

GET /v1/blog/posts/{post}

Retrieve a single blog post.

POST /v1/blog/posts

Create a blog post.

Parameter	Type	Info
`title`	string	Required
`content`	string	Required
`category_id`	integer	Optional
`status`	string	Optional draft, published
`locale`	string	Optional de, en, es, fr

PUT /v1/blog/posts/{post}

Update a blog post.

DEL /v1/blog/posts/{post}

Delete a blog post.

Health Check

Public endpoint (no token required) for monitoring.

GET /api/health

Returns the server status. No authentication required.

// Response 200 { "status": "ok", "timestamp": "2026-02-24T12:00:00Z" }

Ready to use the API?

Create a free account, grab your token under Settings → API and get going. 50 free credits, no credit card.