{"openapi":"3.1.0","info":{"title":"sociallinks.dev API","version":"1.0.0","summary":"One creator profile in, every account out.","description":"Send one creator's Instagram, TikTok, YouTube or X profile URL and get their accounts on the other platforms, each with a verdict, a net confidence score and the evidence behind it. Lists go through /v1/batches. Billing: 1 credit per creator when we find at least one account beyond the one you sent; lookups that find nothing, and failed lookups, are free. Repeating a creator your account paid for in the last 30 days is free. Credits are the same ones the website uses; buy packs at https://sociallinks.dev/pricing."},"servers":[{"url":"https://sociallinks.dev"}],"security":[{"bearer":[]},{"apiKeyHeader":[]}],"paths":{"/v1/resolve":{"post":{"operationId":"resolveCreator","summary":"Look up one creator","description":"Finds the creator's other accounts. Typically 10–40 seconds for a fresh lookup; instant for one we already have. Fresh lookups are limited to 5 per minute per key; send lists to /v1/batches.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"$ref":"#/components/schemas/ProfileUrl"}}}}}},"responses":{"200":{"description":"The creator and their accounts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Creator"}}},"headers":{"X-Credits-Remaining":{"$ref":"#/components/schemas/CreditsHeader"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/OutOfCredits"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/LookupFailed"}}},"get":{"operationId":"resolveCreatorGet","summary":"Look up one creator (query string)","parameters":[{"name":"url","in":"query","required":true,"schema":{"$ref":"#/components/schemas/ProfileUrl"}}],"responses":{"200":{"description":"The creator and their accounts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Creator"}}},"headers":{"X-Credits-Remaining":{"$ref":"#/components/schemas/CreditsHeader"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/OutOfCredits"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/LookupFailed"}}}},"/v1/batches":{"post":{"operationId":"createBatch","summary":"Queue a list of creators","description":"Up to 500 profile URLs per batch. Each row is charged only when it finds accounts; rows run in the background. Poll GET /v1/batches/{id} or download the CSV when it's done.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["urls"],"properties":{"urls":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/ProfileUrl"},"maxItems":500},{"type":"string","description":"One URL per line (commas and tabs also split)."}]},"name":{"type":"string","maxLength":120,"description":"A label for the batch."}}}}}},"responses":{"201":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","required":["id","rows"],"properties":{"id":{"type":"string","format":"uuid"},"rows":{"type":"integer"},"invalid":{"type":"integer","description":"Rows that aren't a profile URL; they are skipped and never charged."},"duplicates":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/OutOfCredits"},"429":{"$ref":"#/components/responses/RateLimited"}}},"get":{"operationId":"listBatches","summary":"Your recent batches","responses":{"200":{"description":"Newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"batches":{"type":"array","items":{"$ref":"#/components/schemas/Batch"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/batches/{id}":{"get":{"operationId":"getBatch","summary":"A batch and its rows","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The batch.","content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"$ref":"#/components/schemas/Batch"},"items":{"type":"array","items":{"$ref":"#/components/schemas/BatchItem"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/batches/{id}/export":{"get":{"operationId":"exportBatch","summary":"Download a batch as CSV","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"One row per profile sent, one column per platform.","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/batches/{id}/cancel":{"post":{"operationId":"cancelBatch","summary":"Stop a batch","description":"Rows not started yet are skipped and never charged; rows already running finish.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Stopped.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/balance":{"get":{"operationId":"getBalance","summary":"Your credit balance","responses":{"200":{"description":"Credits left.","content":{"application/json":{"schema":{"type":"object","required":["credits"],"properties":{"credits":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Authorization: Bearer sl_… (create keys at https://sociallinks.dev/dashboard/api#api-keys)."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"}},"headers":{},"schemas":{"ProfileUrl":{"type":"string","maxLength":500,"description":"A creator's profile page on Instagram, TikTok, YouTube or X. Posts, reels, videos and bare @handles are refused.","examples":["https://www.instagram.com/mkbhd","https://www.youtube.com/@mkbhd"]},"CreditsHeader":{"description":"Credits left after this request.","schema":{"type":"integer"}},"Creator":{"type":"object","required":["creator","profiles","websites"],"properties":{"creator":{"type":"object","properties":{"id":{"type":"string","description":"Stable id for the creator, derived from the profile sent."},"name":{"type":"string"},"kind":{"type":"string","enum":["person","brand","organization","media","unknown"]},"bio":{"type":["string","null"]},"image":{"type":["string","null"]},"aliases":{"type":"array","items":{"type":"string"}},"total_audience":{"type":["integer","null"]}}},"profiles":{"type":"array","items":{"$ref":"#/components/schemas/Profile"},"description":"The profile you sent comes first (verdict seed)."},"websites":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"kind":{"type":"string"},"label":{"type":"string"}}}},"identity_confidence":{"type":"number","minimum":0,"maximum":1},"rejected":{"type":"integer","description":"Candidates checked and ruled out."}}},"Profile":{"type":"object","properties":{"platform":{"type":"string","examples":["instagram","tiktok","youtube","x","twitch"]},"handle":{"type":"string"},"platform_id":{"type":["string","null"],"description":"The platform's own id for the account, e.g. YouTube's UC… channel ID."},"url":{"type":"string"},"links":{"type":"array","description":"Every link we know for the account. A YouTube channel has its @handle URL and its /channel/UC… URL.","items":{"type":"object","properties":{"kind":{"type":"string","enum":["handle","channel_id","url"]},"url":{"type":"string"}}}},"owned_by_other_creator":{"type":"boolean","description":"One of its links already belongs to a different creator in our records, so it scores lower."},"followers":{"type":["integer","null"]},"verdict":{"type":"string","enum":["seed","confirmed","likely","uncertain"]},"net_confidence":{"type":"number","minimum":0,"maximum":1,"description":"Search score and identity check combined."},"search_score":{"type":["number","null"],"minimum":0,"maximum":1},"jev_score":{"type":["number","null"],"minimum":0,"maximum":1,"description":"The identity check's probability that this is the same creator."},"confidence":{"type":"number","description":"Same as jev_score, kept for older integrations."},"evidence":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"detail":{"type":"string"},"source":{"type":["string","null"]}}}}}},"Batch":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"status":{"type":"string","enum":["queued","processing","completed","partial","failed","canceled"]},"total":{"type":"integer"},"succeeded":{"type":"integer"},"empty":{"type":"integer"},"failed":{"type":"integer"},"skipped":{"type":"integer"},"charged":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}}},"BatchItem":{"type":"object","properties":{"position":{"type":"integer"},"input":{"type":"object","properties":{"url":{"type":"string"}}},"status":{"type":"string","enum":["queued","processing","succeeded","empty","failed","skipped"]},"charged":{"type":"integer"},"error_code":{"type":["string","null"]},"result":{"type":["object","null"],"properties":{"name":{"type":"string"},"profiles":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"handle":{"type":"string"},"url":{"type":"string"},"verdict":{"type":"string"}}}},"notFound":{"type":"array","items":{"type":"string"},"description":"Platforms we searched and found nothing on."}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"code":{"type":"string","enum":["login_required","invalid_api_key","out_of_credits"]}}}}}},"responses":{"BadRequest":{"description":"Not a profile URL, or the body is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"No API key, or the key is unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"OutOfCredits":{"description":"No credits left (code out_of_credits).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many fresh lookups; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}},"LookupFailed":{"description":"The lookup broke on our side. You weren't charged; try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such batch on this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"The batch has already finished.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}