curl --request GET \
--url https://api.heralded.ai/v1/brands/{brand_id}/actions \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.heralded.ai/v1/brands/{brand_id}/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.heralded.ai/v1/brands/{brand_id}/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.heralded.ai/v1/brands/{brand_id}/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.heralded.ai/v1/brands/{brand_id}/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.heralded.ai/v1/brands/{brand_id}/actions")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heralded.ai/v1/brands/{brand_id}/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{
"actions": [
{
"citation_count": 0,
"completed_at": "2026-09-01T10:00:00Z",
"created_at": "2026-08-15T10:00:00Z",
"delivered_at": "2026-09-01T10:00:00Z",
"demand": "Verified",
"detail": "Answers comparing agency CRMs cite Rival's page, not yours.",
"done_when": null,
"ending": null,
"evidence": null,
"first_citation": null,
"focus": {
"id": null,
"kind": "outside",
"name": null
},
"gain": null,
"grounds": null,
"group": "settled",
"holder": null,
"id": "9a7b5c3d-1e2f-4a6b-8c0d-2e4f6a8b0c1d",
"kind": "create_content",
"kind_tag": null,
"member": "writer",
"not_seen_since_run": null,
"note": null,
"outcome": "verified_up",
"paid_off_at": "2026-09-08T10:00:00Z",
"placed_position": null,
"preview": null,
"route": "content",
"scheduled_for": null,
"stage": "verify",
"started_at": "2026-08-16T10:00:00Z",
"title": "Publish a comparison page against Rival",
"tracking": [],
"wait": null,
"waiting_since": null,
"write_language": null,
"write_language_locked": false,
"write_language_source": null
}
],
"limit": 20,
"meta": {
"data_as_of": null,
"last_attempt_failed": false,
"partial": false,
"query": {},
"surfaces": {},
"updating": false
},
"next_cursor": null,
"offset": 0,
"suggestion_allowance": null,
"suggestions_kept": 0,
"total": 1
}{
"code": "invalid_cursor",
"detail": "The cursor is invalid or belongs to a different query.",
"instance": "example-request-id",
"status": 400,
"title": "Bad Request",
"type": "https://docs.heralded.ai/errors-and-limits#invalid_cursor"
}{
"code": "invalid_token",
"detail": "The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.",
"instance": "example-request-id",
"status": 401,
"title": "Unauthorized",
"type": "https://docs.heralded.ai/errors-and-limits#invalid_token"
}{
"code": "insufficient_scope",
"detail": "The credential does not have the scope this operation requires.",
"instance": "example-request-id",
"status": 403,
"title": "Forbidden",
"type": "https://docs.heralded.ai/errors-and-limits#insufficient_scope"
}{
"code": "not_found",
"detail": "Nothing here that this API key can read.",
"instance": "example-request-id",
"status": 404,
"title": "Not Found",
"type": "https://docs.heralded.ai/errors-and-limits#not_found"
}{
"code": "workspace_archived",
"detail": "The API key's organization is archived.",
"instance": "example-request-id",
"status": 409,
"title": "Conflict",
"type": "https://docs.heralded.ai/errors-and-limits#workspace_archived"
}{
"code": "invalid_request",
"detail": "The request's parameters are invalid; `errors` names each one.",
"errors": [
{
"loc": [
"query",
"limit"
],
"msg": "Input should be less than or equal to 100",
"type": "less_than_equal"
}
],
"instance": "example-request-id",
"status": 422,
"title": "Unprocessable Content",
"type": "https://docs.heralded.ai/errors-and-limits#invalid_request"
}{
"code": "rate_limited",
"detail": "This caller is past its requests for the minute. Retry after the seconds in Retry-After.",
"instance": "example-request-id",
"rate_limit": {
"limit": 120,
"remaining": 0,
"reset": 60,
"window": 60
},
"status": 429,
"title": "Too Many Requests",
"type": "https://docs.heralded.ai/errors-and-limits#rate_limited"
}Get Actions
Proposed actions (group new) come as this week’s (above the floor, at most two of one play), then the backlog, each in the brand’s order then by priority; other groups newest first. With assignee=mine_or_open, your_input is oldest-waiting first and includes stopped site checks. Dispatchers see their own work and work with no dispatching owner; readers without dispatch and service tokens see all work. waiting_since dates the ask. Each carries its grounds, gain band, done-when and what Heralded tracks.
curl --request GET \
--url https://api.heralded.ai/v1/brands/{brand_id}/actions \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.heralded.ai/v1/brands/{brand_id}/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.heralded.ai/v1/brands/{brand_id}/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.heralded.ai/v1/brands/{brand_id}/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.heralded.ai/v1/brands/{brand_id}/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.heralded.ai/v1/brands/{brand_id}/actions")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heralded.ai/v1/brands/{brand_id}/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{
"actions": [
{
"citation_count": 0,
"completed_at": "2026-09-01T10:00:00Z",
"created_at": "2026-08-15T10:00:00Z",
"delivered_at": "2026-09-01T10:00:00Z",
"demand": "Verified",
"detail": "Answers comparing agency CRMs cite Rival's page, not yours.",
"done_when": null,
"ending": null,
"evidence": null,
"first_citation": null,
"focus": {
"id": null,
"kind": "outside",
"name": null
},
"gain": null,
"grounds": null,
"group": "settled",
"holder": null,
"id": "9a7b5c3d-1e2f-4a6b-8c0d-2e4f6a8b0c1d",
"kind": "create_content",
"kind_tag": null,
"member": "writer",
"not_seen_since_run": null,
"note": null,
"outcome": "verified_up",
"paid_off_at": "2026-09-08T10:00:00Z",
"placed_position": null,
"preview": null,
"route": "content",
"scheduled_for": null,
"stage": "verify",
"started_at": "2026-08-16T10:00:00Z",
"title": "Publish a comparison page against Rival",
"tracking": [],
"wait": null,
"waiting_since": null,
"write_language": null,
"write_language_locked": false,
"write_language_source": null
}
],
"limit": 20,
"meta": {
"data_as_of": null,
"last_attempt_failed": false,
"partial": false,
"query": {},
"surfaces": {},
"updating": false
},
"next_cursor": null,
"offset": 0,
"suggestion_allowance": null,
"suggestions_kept": 0,
"total": 1
}{
"code": "invalid_cursor",
"detail": "The cursor is invalid or belongs to a different query.",
"instance": "example-request-id",
"status": 400,
"title": "Bad Request",
"type": "https://docs.heralded.ai/errors-and-limits#invalid_cursor"
}{
"code": "invalid_token",
"detail": "The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.",
"instance": "example-request-id",
"status": 401,
"title": "Unauthorized",
"type": "https://docs.heralded.ai/errors-and-limits#invalid_token"
}{
"code": "insufficient_scope",
"detail": "The credential does not have the scope this operation requires.",
"instance": "example-request-id",
"status": 403,
"title": "Forbidden",
"type": "https://docs.heralded.ai/errors-and-limits#insufficient_scope"
}{
"code": "not_found",
"detail": "Nothing here that this API key can read.",
"instance": "example-request-id",
"status": 404,
"title": "Not Found",
"type": "https://docs.heralded.ai/errors-and-limits#not_found"
}{
"code": "workspace_archived",
"detail": "The API key's organization is archived.",
"instance": "example-request-id",
"status": 409,
"title": "Conflict",
"type": "https://docs.heralded.ai/errors-and-limits#workspace_archived"
}{
"code": "invalid_request",
"detail": "The request's parameters are invalid; `errors` names each one.",
"errors": [
{
"loc": [
"query",
"limit"
],
"msg": "Input should be less than or equal to 100",
"type": "less_than_equal"
}
],
"instance": "example-request-id",
"status": 422,
"title": "Unprocessable Content",
"type": "https://docs.heralded.ai/errors-and-limits#invalid_request"
}{
"code": "rate_limited",
"detail": "This caller is past its requests for the minute. Retry after the seconds in Retry-After.",
"instance": "example-request-id",
"rate_limit": {
"limit": 120,
"remaining": 0,
"reset": 60,
"window": 60
},
"status": 429,
"title": "Too Many Requests",
"type": "https://docs.heralded.ai/errors-and-limits#rate_limited"
}Authorizations
An organisation service token, sent as Authorization: Bearer hrld_svc_... Scopes: scans:start starts service scans; scans:read reads them; managed:read reads brands, profile, overview, scores, competitors, actions and Snapshots in actively managed organisations; managed:share makes their restricted Snapshots unlisted.
Query Parameters
me selects actions assigned to you; heralded selects actions with no person assigned. mine_or_open selects your own and unassigned work, including work whose owner cannot start work. Readers without permission to start work and service tokens see everyone. Omit for anyone.
me, heralded, mine_or_open Keep the live actions about one subject: prompt:<uid>, topic:<id>, keyword:<id>, figure:<axis>, source:<domain>, competitor:<key>, engine:<id> or page:<url>. A subject the brand does not have matches nothing.
512^(prompt|topic|keyword|figure|source|competitor|engine|page):.+$Response
Successful Response