SignalShelf · Developer documentation

Keep a useful creator shortlist

Save a profile from your own successful lookup, review the shelf, and export selected research as a CSV file.

ParameterTypeRequiredDescription
event_idstringYesFor 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.

REQUEST EXAMPLE
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"}'

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.

Explore the API in your workspace. Sample results and accepted cache hits cost zero credits. Open the playground →