Keep a useful creator shortlist
Save a profile from your own successful lookup, review the shelf, and export selected research as a CSV file.
| Parameter | Type | Required | Description |
|---|---|---|---|
event_id | string | Yes | For POST /api/saved: successful profile lookup event belonging to the authenticated account. |
Save a lookup result
POST /api/saved accepts event_id from a successful lookup’s meta object. You cannot submit arbitrary profile JSON or another account’s event ID. Saving the same platform and handle updates its existing shelf entry. The endpoint returns HTTP 201 with success true.
curl "$SIGNALSHELF_BASE_URL/api/saved" \
-H "Content-Type: application/json" \
-H "x-api-key: $SIGNALSHELF_API_KEY" \
--data '{"event_id":"REPLACE_WITH_YOUR_LOOKUP_EVENT_ID"}'// Run in a server environment. Never expose the key in client-side code.
const response = await fetch(`${process.env.SIGNALSHELF_BASE_URL}/api/saved`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.SIGNALSHELF_API_KEY,
},
body: JSON.stringify({"event_id":"REPLACE_WITH_YOUR_LOOKUP_EVENT_ID"}),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error?.code}: ${result.error?.message}`);
console.log(result);# Server-side Python; install requests if needed.
import os
import requests
response = requests.post(
os.environ['SIGNALSHELF_BASE_URL'] + "/api/saved",
headers={'x-api-key': os.environ['SIGNALSHELF_API_KEY']},
json={'event_id': 'REPLACE_WITH_YOUR_LOOKUP_EVENT_ID'},
timeout=45,
)
result = response.json()
response.raise_for_status()
print(result)Snapshot behavior
For a live lookup, saving copies the currently stored profile for that platform and handle into your shelf; another refresh may have updated the shared cache after your original event. Saving a demo event stores its labeled illustrative sample. If a live result is no longer available in cache, the endpoint returns 409 RESULT_EXPIRED. Refresh and save again.
List and remove
GET /api/saved returns a creators array ordered by saved_at, newest first. Each record contains id, platform, handle, data, and saved_at, along with its account ownership field. DELETE /api/saved/{id} removes your shelf entry and returns success true; unknown or other-account IDs return 404. Removing a shelf entry does not clear the shared public cache.
Export CSV
GET /api/export.csv returns a downloadable signalshelf-creators.csv file. Columns are platform, handle, name, followers, following, posts, url, and sample. The sample column helps distinguish illustrative entries. Export reads your shelf without triggering live fetches or consuming credits. Spreadsheet-sensitive values are escaped for safer CSV handling.
A shelf is not a live monitor
Saved entries persist separately from the seven-day cache. They do not automatically refresh. The current export does not contain historical follower changes or a complete audit trail. For current metrics, perform a new lookup and update the saved entry.