curl --request GET \
--url https://api.rankspot.ai/v1/actions \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.rankspot.ai/v1/actions"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.rankspot.ai/v1/actions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.rankspot.ai/v1/actions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.rankspot.ai/v1/actions"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.rankspot.ai/v1/actions")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.rankspot.ai/v1/actions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": {
"total": 100,
"offset": 0,
"limit": 100,
"count": 10,
"items": [
{
"id": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"type": "write_article",
"title": "How to Start a Blog in 2024",
"status": "new",
"fanoutQueries": [
{
"id": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"query": "best screen recording software for mac 2026"
}
],
"keywords": [
{
"id": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"keyword": "start a blog"
}
],
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"slug": "how-to-start-a-blog",
"shortDescription": "Cited in 6 ChatGPT answers — you are in none.",
"description": "A comprehensive guide for beginners.",
"additionalInstructions": "Focus on WordPress.",
"completedAt": "<string>",
"categoryId": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"articleId": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"citationId": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"backlinkId": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"competitorId": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"citation": {
"id": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"url": "https://zapier.com/blog/best-screen-recorders/",
"domain": "zapier.com",
"isOwnDomain": false,
"title": "The 12 best screen recorders"
},
"backlink": {
"id": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"domainFrom": "ahrefs.com",
"urlFrom": "https://ahrefs.com/blog/seo-tools/",
"dofollow": true,
"domainFromRank": 91
},
"competitor": {
"id": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"name": "Ahrefs",
"domain": "ahrefs.com"
}
}
]
}
}List actions
Returns a paginated list of actions ordered by position then creation date. Filter by status and types, both of which accept comma-separated or repeated values, or a search substring matching the title or description. Archived actions are never returned.
curl --request GET \
--url https://api.rankspot.ai/v1/actions \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.rankspot.ai/v1/actions"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.rankspot.ai/v1/actions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.rankspot.ai/v1/actions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.rankspot.ai/v1/actions"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.rankspot.ai/v1/actions")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.rankspot.ai/v1/actions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": {
"total": 100,
"offset": 0,
"limit": 100,
"count": 10,
"items": [
{
"id": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"type": "write_article",
"title": "How to Start a Blog in 2024",
"status": "new",
"fanoutQueries": [
{
"id": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"query": "best screen recording software for mac 2026"
}
],
"keywords": [
{
"id": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"keyword": "start a blog"
}
],
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"slug": "how-to-start-a-blog",
"shortDescription": "Cited in 6 ChatGPT answers — you are in none.",
"description": "A comprehensive guide for beginners.",
"additionalInstructions": "Focus on WordPress.",
"completedAt": "<string>",
"categoryId": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"articleId": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"citationId": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"backlinkId": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"competitorId": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"citation": {
"id": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"url": "https://zapier.com/blog/best-screen-recorders/",
"domain": "zapier.com",
"isOwnDomain": false,
"title": "The 12 best screen recorders"
},
"backlink": {
"id": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"domainFrom": "ahrefs.com",
"urlFrom": "https://ahrefs.com/blog/seo-tools/",
"dofollow": true,
"domainFromRank": 91
},
"competitor": {
"id": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
"name": "Ahrefs",
"domain": "ahrefs.com"
}
}
]
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
x >= 01 <= x <= 100Search by title or description substring
Filter by status. Accepts comma-separated or repeated params: ?status=new,in_progress
new: not started · in_progress: an executor is running · processed: finished. Same vocabulary as backlinks, citations and people-also-ask, with the extra middle state only actions can have.
new, in_progress, processed Filter by kind of work. Accepts comma-separated or repeated params: ?types=write_article. Omit for every type. Validated as strings rather than against the enum, so an unknown value returns nothing instead of a 400 once more types exist.
What kind of work an action is, and what else the body needs:
write_article— plan a piece of content, then call POST /v1/actions/:id/generate to write it. Requires no target.update_article— any edit to an existing article, with the instruction in additionalInstructions. RequiresarticleId.earn_link— go after a referring domain your competitors have. RequiresbacklinkId.get_cited— get onto a page AI engines already cite. RequirescitationId.reply_thread— reply on a cited Reddit or Quora thread. RequirescitationId.record_video— make a video of your own, since you cannot be added to someone else's. RequirescitationId.track_competitor— start tracking a brand RankSpot discovered in AI answers. RequirescompetitorId.add_prompt— track a question buyers ask that no existing prompt covers. Requires no target.publish_article— push a finished article to the workspace integrations. RequiresarticleId.request_indexing— ask Google to index a published page it has missed. RequiresarticleId.other— anything you just want written down. Requires no target.
write_article, update_article, earn_link, get_cited, reply_thread, record_video, track_competitor, add_prompt, publish_article, request_indexing, other Response
Hide child attributes
Hide child attributes
100
0
100
10
Hide child attributes
Hide child attributes
"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"
What kind of work this is.
write_article, update_article, earn_link, get_cited, reply_thread, record_video, track_competitor, add_prompt, publish_article, request_indexing, other "write_article"
"How to Start a Blog in 2024"
new: not started · in_progress: an executor is running · processed: finished. Same vocabulary as backlinks, citations and people-also-ask, with the extra middle state only actions can have.
new, in_progress, processed "new"
The fanout searches themselves, on the article types. Provenance rather than a target: they are what justified the work, not where it happens. A set, because engines phrase one intent many ways.
"how-to-start-a-blog"
The one line shown under the title in a list. Null on actions created before this field existed.
"Cited in 6 ChatGPT answers — you are in none."
The fuller explanation, shown when the action is opened. On write_article this is the brief handed to the generator instead.
"A comprehensive guide for beginners."
"Focus on WordPress."
When the work finished.
"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"
The article this action produced (write_article) or edits (update_article).
"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"
The cited page or thread, on get_cited and reply_thread. Null once the citation itself is gone, which does not remove the action.
"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"
The referring domain to go after, on earn_link.
"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"
The brand to start tracking, on track_competitor.
"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"
The cited page itself, on get_cited and reply_thread. Carries the url to open and the citation count the reason is built from.
Hide child attributes
Hide child attributes
"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"
"https://zapier.com/blog/best-screen-recorders/"
"zapier.com"
The page is on your own domain.
false
"The 12 best screen recorders"
The referring domain itself, on earn_link. urlFrom is the page carrying the competitor link.
Hide child attributes
Hide child attributes
"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"
"ahrefs.com"
The page carrying the competitor link.
"https://ahrefs.com/blog/seo-tools/"
true
91
