curl --request GET \
--url https://www.getsurfaced.ai/api/v1/briefs \
--header 'Authorization: Bearer <token>' \
--header 'X-Workspace-Id: <x-workspace-id>'import requests
url = "https://www.getsurfaced.ai/api/v1/briefs"
headers = {
"X-Workspace-Id": "<x-workspace-id>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'X-Workspace-Id': '<x-workspace-id>', Authorization: 'Bearer <token>'}
};
fetch('https://www.getsurfaced.ai/api/v1/briefs', 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://www.getsurfaced.ai/api/v1/briefs",
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>",
"X-Workspace-Id: <x-workspace-id>"
],
]);
$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://www.getsurfaced.ai/api/v1/briefs"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Workspace-Id", "<x-workspace-id>")
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://www.getsurfaced.ai/api/v1/briefs")
.header("X-Workspace-Id", "<x-workspace-id>")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://www.getsurfaced.ai/api/v1/briefs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Workspace-Id"] = '<x-workspace-id>'
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"title": "<string>",
"keyword": "<string>",
"persona": "<string>",
"region": "<string>",
"language": "<string>",
"intent": "<string>",
"tags": [
"<string>"
],
"notes": "<string>",
"category": "<string>",
"source": "<string>",
"position": 123,
"status": "draft",
"locked": true,
"run": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"state": "queued",
"paused": true,
"executionMode": "<string>",
"latestActivityAt": "2023-11-07T05:31:56Z",
"targets": [
{
"marketRef": "<string>",
"language": "<string>",
"locale": "<string>",
"state": "queued",
"articleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
]
},
"markets": [
{
"marketRef": "<string>",
"name": "<string>",
"countries": [
"<string>"
],
"language": "<string>"
}
],
"content": {
"articleStructure": "<string>",
"culturalTone": "<string>",
"formality": "<string>",
"addressFormality": "<string>",
"wordCount": {
"min": 123,
"target": 123,
"max": 123
},
"requiredSections": [
"<string>"
],
"blockPreferences": {},
"templateId": "<string>",
"faqPosition": "<string>",
"cta": {},
"targetRegions": [
"<string>"
]
},
"gap": {
"gapIds": [
"<string>"
],
"suggestionId": "<string>",
"targetScope": "<unknown>"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"state": "pending",
"input_tags": [
"<string>"
],
"metadata": {},
"source_suggestion_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"source_gap_ids": [
"<string>"
],
"article_structure": "<string>",
"cultural_tone": "<string>",
"formality": "<string>",
"address_formality": "<string>",
"word_count_min": 123,
"word_count_target": 123,
"word_count_max": 123,
"required_sections": [
"<string>"
],
"block_preferences": {},
"template_id": "<string>",
"faq_position": "<string>",
"cta": {},
"target_regions": [
"<string>"
],
"target_markets": [
"<unknown>"
],
"locale": "<string>",
"locales": [
"<string>"
],
"cultural_overrides": {},
"idea_text": "<string>",
"primary_keyword": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
],
"meta": {
"cursor": "<string>",
"hasMore": true,
"total": 123
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "<string>",
"details": {}
}
}List Content Briefs in the active workspace
Returns Content Briefs with cursor pagination. Each Brief has a lifecycle status (draft, awaiting_approval, approved, writing, articles_to_review, published, didnt_finish) and, once writing has started, a run with one target per market and language and its writing state (queued, writing, checking, finishing, didnt_finish, dropped, written). Start writing a Brief with POST /briefs/{id}/run (approve a waiting plan with POST /briefs/{id}/run/approve); GET /briefs/{id}/run has each target’s errors and the Run’s counts, and POST /briefs/{id}/run/retry writes the targets that didn’t finish again. Without list options the list is in manual order (position) and state (the deprecated stored state) and language (the Brief’s own language) filter exactly. Any of search, sort, direction, view, runState, intent or market selects the searchable list instead: language and market then match the Brief’s markets, runState filters by its Run, state is a 422, and meta.total can be null. Keep the same parameters when following meta.cursor. The snake_case fields are the representation from before camelCase: deprecated, kept with their old values until the API sunset, each naming its replacement, and announced by a DEPRECATED_FIELDS warning. The Surfaced-Version header is no longer needed and is ignored. If the Briefs’ progress cannot be read, the response still has every other field, with status, locked and run null and a PARTIAL_DATA warning; retry later for them.
curl --request GET \
--url https://www.getsurfaced.ai/api/v1/briefs \
--header 'Authorization: Bearer <token>' \
--header 'X-Workspace-Id: <x-workspace-id>'import requests
url = "https://www.getsurfaced.ai/api/v1/briefs"
headers = {
"X-Workspace-Id": "<x-workspace-id>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'X-Workspace-Id': '<x-workspace-id>', Authorization: 'Bearer <token>'}
};
fetch('https://www.getsurfaced.ai/api/v1/briefs', 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://www.getsurfaced.ai/api/v1/briefs",
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>",
"X-Workspace-Id: <x-workspace-id>"
],
]);
$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://www.getsurfaced.ai/api/v1/briefs"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Workspace-Id", "<x-workspace-id>")
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://www.getsurfaced.ai/api/v1/briefs")
.header("X-Workspace-Id", "<x-workspace-id>")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://www.getsurfaced.ai/api/v1/briefs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Workspace-Id"] = '<x-workspace-id>'
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"title": "<string>",
"keyword": "<string>",
"persona": "<string>",
"region": "<string>",
"language": "<string>",
"intent": "<string>",
"tags": [
"<string>"
],
"notes": "<string>",
"category": "<string>",
"source": "<string>",
"position": 123,
"status": "draft",
"locked": true,
"run": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"state": "queued",
"paused": true,
"executionMode": "<string>",
"latestActivityAt": "2023-11-07T05:31:56Z",
"targets": [
{
"marketRef": "<string>",
"language": "<string>",
"locale": "<string>",
"state": "queued",
"articleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
]
},
"markets": [
{
"marketRef": "<string>",
"name": "<string>",
"countries": [
"<string>"
],
"language": "<string>"
}
],
"content": {
"articleStructure": "<string>",
"culturalTone": "<string>",
"formality": "<string>",
"addressFormality": "<string>",
"wordCount": {
"min": 123,
"target": 123,
"max": 123
},
"requiredSections": [
"<string>"
],
"blockPreferences": {},
"templateId": "<string>",
"faqPosition": "<string>",
"cta": {},
"targetRegions": [
"<string>"
]
},
"gap": {
"gapIds": [
"<string>"
],
"suggestionId": "<string>",
"targetScope": "<unknown>"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"state": "pending",
"input_tags": [
"<string>"
],
"metadata": {},
"source_suggestion_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"source_gap_ids": [
"<string>"
],
"article_structure": "<string>",
"cultural_tone": "<string>",
"formality": "<string>",
"address_formality": "<string>",
"word_count_min": 123,
"word_count_target": 123,
"word_count_max": 123,
"required_sections": [
"<string>"
],
"block_preferences": {},
"template_id": "<string>",
"faq_position": "<string>",
"cta": {},
"target_regions": [
"<string>"
],
"target_markets": [
"<unknown>"
],
"locale": "<string>",
"locales": [
"<string>"
],
"cultural_overrides": {},
"idea_text": "<string>",
"primary_keyword": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
],
"meta": {
"cursor": "<string>",
"hasMore": true,
"total": 123
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "<string>",
"details": {}
}
}Authorizations
API key (sk_live_...) created at https://www.getsurfaced.ai/app/settings/account/api-keys