Update an action

curl --request PATCH \
  --url https://api.rankspot.ai/v1/actions/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "How to Start a Blog in 2024",
  "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.",
  "categoryId": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
  "keywordIds": [
    "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"
  ],
  "status": "processed",
  "archived": true
}
'

import requests

url = "https://api.rankspot.ai/v1/actions/{id}"

payload = {
    "title": "How to Start a Blog in 2024",
    "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.",
    "categoryId": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
    "keywordIds": ["6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"],
    "status": "processed",
    "archived": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: 'How to Start a Blog in 2024',
    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.',
    categoryId: '6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94',
    keywordIds: ['6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94'],
    status: 'processed',
    archived: true
  })
};

fetch('https://api.rankspot.ai/v1/actions/{id}', 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/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'How to Start a Blog in 2024',
    '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.',
    'categoryId' => '6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94',
    'keywordIds' => [
        '6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94'
    ],
    'status' => 'processed',
    'archived' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rankspot.ai/v1/actions/{id}"

	payload := strings.NewReader("{\n  \"title\": \"How to Start a Blog in 2024\",\n  \"slug\": \"how-to-start-a-blog\",\n  \"shortDescription\": \"Cited in 6 ChatGPT answers — you are in none.\",\n  \"description\": \"A comprehensive guide for beginners.\",\n  \"additionalInstructions\": \"Focus on WordPress.\",\n  \"categoryId\": \"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94\",\n  \"keywordIds\": [\n    \"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94\"\n  ],\n  \"status\": \"processed\",\n  \"archived\": true\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.rankspot.ai/v1/actions/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"How to Start a Blog in 2024\",\n  \"slug\": \"how-to-start-a-blog\",\n  \"shortDescription\": \"Cited in 6 ChatGPT answers — you are in none.\",\n  \"description\": \"A comprehensive guide for beginners.\",\n  \"additionalInstructions\": \"Focus on WordPress.\",\n  \"categoryId\": \"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94\",\n  \"keywordIds\": [\n    \"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94\"\n  ],\n  \"status\": \"processed\",\n  \"archived\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.rankspot.ai/v1/actions/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"How to Start a Blog in 2024\",\n  \"slug\": \"how-to-start-a-blog\",\n  \"shortDescription\": \"Cited in 6 ChatGPT answers — you are in none.\",\n  \"description\": \"A comprehensive guide for beginners.\",\n  \"additionalInstructions\": \"Focus on WordPress.\",\n  \"categoryId\": \"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94\",\n  \"keywordIds\": [\n    \"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94\"\n  ],\n  \"status\": \"processed\",\n  \"archived\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

Actions

Update an action

Edits an action’s content — title, slug, shortDescription, description, additionalInstructions, categoryId, keywordIds — or its bookkeeping: status and archived. Passing keywordIds replaces the full set of linked keywords.

Content can only be edited while status is new; once an executor has started the action is locked and a content edit returns action-locked. Bookkeeping stays open: archived at any point, and status on anything that is not currently in_progress — a running generator is reading the row, so reopening or closing it returns action-in-progress.

status: "processed" stamps completedAt and marks the citation or backlink behind the action handled; status: "new" clears completedAt, puts that evidence back on the worklist and undoes a dismissal.

PATCH

https://api.rankspot.ai

actions

{id}

Update an action

curl --request PATCH \
  --url https://api.rankspot.ai/v1/actions/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "How to Start a Blog in 2024",
  "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.",
  "categoryId": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
  "keywordIds": [
    "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"
  ],
  "status": "processed",
  "archived": true
}
'

import requests

url = "https://api.rankspot.ai/v1/actions/{id}"

payload = {
    "title": "How to Start a Blog in 2024",
    "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.",
    "categoryId": "6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94",
    "keywordIds": ["6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"],
    "status": "processed",
    "archived": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: 'How to Start a Blog in 2024',
    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.',
    categoryId: '6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94',
    keywordIds: ['6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94'],
    status: 'processed',
    archived: true
  })
};

fetch('https://api.rankspot.ai/v1/actions/{id}', 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/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'How to Start a Blog in 2024',
    '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.',
    'categoryId' => '6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94',
    'keywordIds' => [
        '6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94'
    ],
    'status' => 'processed',
    'archived' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rankspot.ai/v1/actions/{id}"

	payload := strings.NewReader("{\n  \"title\": \"How to Start a Blog in 2024\",\n  \"slug\": \"how-to-start-a-blog\",\n  \"shortDescription\": \"Cited in 6 ChatGPT answers — you are in none.\",\n  \"description\": \"A comprehensive guide for beginners.\",\n  \"additionalInstructions\": \"Focus on WordPress.\",\n  \"categoryId\": \"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94\",\n  \"keywordIds\": [\n    \"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94\"\n  ],\n  \"status\": \"processed\",\n  \"archived\": true\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.rankspot.ai/v1/actions/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"How to Start a Blog in 2024\",\n  \"slug\": \"how-to-start-a-blog\",\n  \"shortDescription\": \"Cited in 6 ChatGPT answers — you are in none.\",\n  \"description\": \"A comprehensive guide for beginners.\",\n  \"additionalInstructions\": \"Focus on WordPress.\",\n  \"categoryId\": \"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94\",\n  \"keywordIds\": [\n    \"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94\"\n  ],\n  \"status\": \"processed\",\n  \"archived\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.rankspot.ai/v1/actions/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"How to Start a Blog in 2024\",\n  \"slug\": \"how-to-start-a-blog\",\n  \"shortDescription\": \"Cited in 6 ChatGPT answers — you are in none.\",\n  \"description\": \"A comprehensive guide for beginners.\",\n  \"additionalInstructions\": \"Focus on WordPress.\",\n  \"categoryId\": \"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94\",\n  \"keywordIds\": [\n    \"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94\"\n  ],\n  \"status\": \"processed\",\n  \"archived\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

string

required

Body

application/json

title

string

Example:

"How to Start a Blog in 2024"

slug

object

Optional slug for the article generated from this action. Pass null to clear it and fall back to deriving the slug from the title at generation time. Must already be a valid slug (lowercase letters, numbers and single hyphens) — it is validated, not rewritten. Must be unique across actions and articles.

Example:

"how-to-start-a-blog"

shortDescription

string

The one line shown under the title in a list.

Example:

"Cited in 6 ChatGPT answers — you are in none."

description

string

Example:

"A comprehensive guide for beginners."

additionalInstructions

string

Example:

"Focus on WordPress."

categoryId

string

Example:

"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"

keywordIds

string[]

Example:

["6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"]

status

enum<string>

Where the action stands. processed closes it and marks the page or link behind it handled; new reopens it and puts that page or link back on the worklist, undoing a dismissal too. in_progress is set by the executor, not here, and while an action is in it neither value is accepted: the generator is reading the row.

Available options:

new,

processed

Example:

"processed"

archived

boolean

Take the action off the board without deciding it, which also hides the page or link behind it from the worklist. false puts both back. The row and its evidence are kept either way; nothing is deleted.

Example:

true

Response

string

required

Example:

"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"

type

enum<string>

required

What kind of work this is.

Available options:

write_article,

update_article,

earn_link,

get_cited,

reply_thread,

record_video,

track_competitor,

add_prompt,

publish_article,

request_indexing,

other

Example:

"write_article"

title

string

required

Example:

"How to Start a Blog in 2024"

status

enum<string>

required

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.

Available options:

new,

in_progress,

processed

Example:

"new"

fanoutQueries

object[]

required

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.

Hide child attributes

fanoutQueries.id

string

required

Example:

"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"

fanoutQueries.query

string

required

Example:

"best screen recording software for mac 2026"

keywords

object[]

required

Hide child attributes

keywords.id

string

required

Example:

"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"

keywords.keyword

string

required

Example:

"start a blog"

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

slug

string | null

Example:

"how-to-start-a-blog"

shortDescription

string | null

The one line shown under the title in a list. Null on actions created before this field existed.

Example:

"Cited in 6 ChatGPT answers — you are in none."

description

string | null

The fuller explanation, shown when the action is opened. On write_article this is the brief handed to the generator instead.

Example:

"A comprehensive guide for beginners."

additionalInstructions

string | null

Example:

"Focus on WordPress."

completedAt

string | null

When the work finished.

categoryId

string | null

Example:

"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"

articleId

string | null

The article this action produced (write_article) or edits (update_article).

Example:

"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"

citationId

string | null

The cited page or thread, on get_cited and reply_thread. Null once the citation itself is gone, which does not remove the action.

Example:

"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"

backlinkId

string | null

The referring domain to go after, on earn_link.

Example:

"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"

competitorId

string | null

The brand to start tracking, on track_competitor.

Example:

"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"

citation

object | null

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

citation.id

string

required

Example:

"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"

citation.url

string

required

Example:

"https://zapier.com/blog/best-screen-recorders/"

citation.domain

string

required

Example:

"zapier.com"

citation.isOwnDomain

boolean

required

The page is on your own domain.

Example:

false

citation.title

string | null

Example:

"The 12 best screen recorders"

backlink

object | null

The referring domain itself, on earn_link. urlFrom is the page carrying the competitor link.

Hide child attributes

backlink.id

string

required

Example:

"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"

backlink.domainFrom

string

required

Example:

"ahrefs.com"

backlink.urlFrom

string

required

The page carrying the competitor link.

Example:

"https://ahrefs.com/blog/seo-tools/"

backlink.dofollow

boolean

required

Example:

true

backlink.domainFromRank

number | null

Example:

91

competitor

object | null

The brand itself, on track_competitor.

Hide child attributes

competitor.id

string

required

Example:

"6b3c1f2e-9d4a-4a7e-b2c1-5f0e8a7d3c94"

competitor.name

string

required

Example:

"Ahrefs"

competitor.domain

string

required

Example:

"ahrefs.com"

Introduction

MCP Server

API Endpoints

Update an action

Authorizations

Path Parameters

Body

Response