Pick your reference creators and competitors

Suggestions arrive with the evidence behind each one (same niche, beats its baseline, picked together by other workspaces) and are accepted or rejected in one call. Browse searches the set and shows how many other workspaces picked a handle, as counts of at least three and never who; the free plan browses 5 times a day. A job started with a member's id and a mode (clone, format or inspiration) works from that person, and the post it makes records which member it came from, so its result is measured against the account's own baseline.

Ask in plain words#

• "add @garyvee as a creator I learn from"
• "who should I be watching in my niche"
• "track my three competitors on TikTok"
• "make a post in the format of this creator's best reel"
• "who else do people who follow this creator pick"

From an agent host (MCP)#

Server: https://shapelessai.com/mcp (add it to your host).

• references_list: The creators, competitors and peers ("creators like me") this account works from, by set, each with its member id, platform, handle and profile url. Pass a member id to jobs_create as referenceId to make a post from that person. Needs the read scope.
• references_add: Add one person to the account's reference set: a handle and platform, or a profile URL, tagged creator, competitor or peer ("creators like me"). Pass suggestionId to accept a references_suggest suggestion. Adding someone already there answers the member with created: false. Picks stay private to the account. Needs the write scope.
• references_remove: Remove a member from the reference set (memberId), or dismiss a suggestion (suggestionId). The reason (not_similar, not_relevant, low_quality, other) teaches the next suggestions. Needs the write scope.
• references_suggest: People we suggest the account follow as references, best first, each with reasons [{code, evidence}] (same_niche, beats_baseline, co_selected, links_to_you, same_format...) to show the human. Accept with references_add {suggestionId}, dismiss with references_remove {suggestionId}. Empty with a note until the reference-suggest job has run for the account. Needs the read scope.
• references_browse: Search the reference graph: the account's own members matching q, how many other workspaces picked a matching handle (counts of at least k = 3, never who), and with platform plus an exact handle, what those workspaces picked beside it ("people who pick X also pick"). Counted per UTC day: Free 5, Spark 50, Growth 500, Studio unlimited; remaining says what is left, a 402 carries the upgrade links. Needs the read scope.

From code (REST)#

Bearer API key with the scope each call names (auth, OpenAPI).

• GET /api/v1/references (read scope): The account's reference sets (creators, competitors, peers) with their members.
• POST /api/v1/references (write scope): Add one person to a reference set: {handle, platform} or {url}, kind creator|competitor|peer, setId? (default set, made on first use), suggestionId?, personName?. Adding someone already in the set answers the member with created: false.
• DELETE /api/v1/references/{id} (write scope): Remove a member (soft). ?reason=not_similar|not_relevant|low_quality|other teaches the suggestions.
• GET /api/v1/references/suggestions (read scope): People we suggest as references, each with reasons [{code, evidence}] and a rank. ?kind=creator|competitor|peer|any, ?limit=1..20. Empty with a note until the reference-suggest job has run for the account.
• POST /api/v1/references/suggestions/{id}/decide (write scope): Accept (adds the person as a member) or reject a suggestion: {decision: accept|reject, kind?, setId?}.
• GET /api/v1/references/browse (read scope): Search the reference graph: your own members matching ?q (and ?platform), the handles other workspaces picked as counts only (at least 3 workspaces, never which), and with platform + an exact handle, what those workspaces picked beside it. Per UTC day: Free 5, Spark 50, Growth 500, Studio unlimited.

The body#

POST /api/v1/references:

• handle string: The account's handle, with or without @.
• platform string: A platform id (GET /api/platforms); read from url when absent.
• url string: A profile URL; enough on its own for the platforms we can read it from.
• kind string (creator, competitor, peer): Default creator. peer = creators like me.
• setId string
• suggestionId string: Adding from GET /api/v1/references/suggestions.
• personName string
• source string (search, import): Only when the person came from a search or an import.

POST /api/v1/references/suggestions/{id}/decide:

• decision string, required (accept, reject)
• kind string (creator, competitor, peer): Overrides the suggested kind on accept.
• setId string

From a terminal (CLI)#

• shapeless references list
• shapeless references add
• shapeless references remove
• shapeless references suggest
• shapeless references browse

Example#

curl -s https://shapelessai.com/api/v1/references -X POST -H "Authorization: Bearer $SHAPELESS_API_KEY" -H "Content-Type: application/json" -d '{"url":"https://www.tiktok.com/@creator","kind":"competitor"}'

// MCP tool call
{ "tool": "references_add", "arguments": { "handle": "creator", "platform": "tiktok", "kind": "competitor" } }

shapeless references add creator --platform tiktok --kind competitor

Refusals#

Where else#

• The mcp docs (markdown)

More in Signal#

List a tool on the Shapeless Directory, or search it · Read performance · Audit a profile · Boost with paid