Skip to main content
POST
Create an action

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
type
enum<string>
required

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. Requires articleId.
  • earn_link — go after a referring domain your competitors have. Requires backlinkId.
  • get_cited — get onto a page AI engines already cite. Requires citationId.
  • reply_thread — reply on a cited Reddit or Quora thread. Requires citationId.
  • record_video — make a video of your own, since you cannot be added to someone else's. Requires citationId.
  • track_competitor — start tracking a brand RankSpot discovered in AI answers. Requires competitorId.
  • 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. Requires articleId.
  • request_indexing — ask Google to index a published page it has missed. Requires articleId.
  • other — anything you just want written down. Requires no target.
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

What to do. Shown as the card title. Required for every type.

Example:

"How to Start a Blog in 2024"

​
shortDescription
string

The one line shown under the title in a list, and for most actions the only text anyone reads. Lead with the evidence and the numbers behind it, do not restate the title. Keep it to a single short sentence.

Example:

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

​
description
string

For write_article this is the brief handed to the generator. For every other type it is the fuller explanation shown when the action is opened, so it can run to a short paragraph.

Example:

"A comprehensive guide for beginners."

​
additionalInstructions
string

Extra guidance. For update_article this carries the actual instruction, which is why every kind of article edit is one type rather than several.

Example:

"Focus on WordPress."

​
slug
object

write_article only; dropped on other types. Slug for the article generated from this action. If omitted or null the slug is derived from the title at generation time. Validated, not rewritten, and must be unique across actions and articles.

Example:

"how-to-start-a-blog"

​
categoryId
string

write_article only; dropped on other types. Category to file the article under.

Example:

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

​
keywordIds
string[]

write_article only; dropped on other types. Tracked keywords to link, which broadens the article's semantic coverage.

Example:
​
articleId
string

update_article, publish_article and request_indexing only, and required for them. The article this is about, from GET /v1/articles. This is the same articleId the response returns.

Example:

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

​
citationId
string

get_cited, reply_thread and record_video only, and required for them. The cited page or thread this is about.

Example:

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

​
backlinkId
string

earn_link only, and required for it. The referring domain to go after.

Example:

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

​
competitorId
string

track_competitor only, and required for it. The brand to start tracking.

Example:

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

​
fanoutQueryIds
string[]

Optional. write_article, update_article and add_prompt only; dropped on other types. The fanout searches that justified this, from rankspot_list_ai_fanout_queries. Send the whole cluster, not one phrasing of it: engines ask the same thing a dozen ways and one article answers all of them. Unlike the fields above this is not a target and not exclusive with them, so send keywordIds too.

Example:

Response

​
id
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.

​
keywords
object[]
required
​
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.

​
backlink
object | null

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

​
competitor
object | null

The brand itself, on track_competitor.