Skip to content

resolveInput

POST
/resolve
curl --request POST \
  --url http://localhost:8080/api/v1/resolve \
  --header 'Content-Type: application/json' \
  --cookie hs_session=<hs_session> \
  --data '{ "input": "example", "hintPlatform": "instagram", "lookupProfiles": true }'

Paste-anything parser. Accepts URLs, share-sheet text, @handles, platform:handle prefixes (also localized platform names such as 小红书 or ไลน์), one per line or mixed. Expands short links (allow-listed hosts only) and looks up public profile names and avatars when the platform allows it. Never creates anything.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
input
required
string
>= 1 characters <= 10000 characters
hintPlatform
string
Allowed values: instagram facebook line wechat bluesky x douyin xiaohongshu truthsocial
lookupProfiles

Fetch public names and avatars where allowed. Agents may set false for speed.

boolean
default: true

Responses

Section titled “Responses”

200

Section titled “200”

Candidates in input order.

Media typeapplication/json
object
candidates
required
Array<object>
object
key
required

Stable within one response.

string
input
required

The fragment this came from.

string
platform
required
string
Allowed values: instagram facebook line wechat bluesky x douyin xiaohongshu truthsocial
handle
required
string
platformUserId
string | null
profileUrl
required
string format: uri
displayName
string | null
avatarUrl

Remote URL for preview only.

string | null
confidence
required
string
Allowed values: high medium low
alternatives

Other platforms this bare handle could belong to.

Array<string>
Allowed values: instagram facebook line wechat bluesky x douyin xiaohongshu truthsocial
existing
One of:
null
suggestedPersonId
One of:
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
warnings
required
Array<string>
unrecognized
required
Array<string>

Examples

Exampleseed

Derived from fixtures/seed.json.

{
  "candidates": [
    {
      "avatarUrl": null,
      "confidence": "high",
      "displayName": null,
      "existing": {
        "accountId": "acc_01j93283xpmc4y04hy7rmmt7y7",
        "personId": "per_01j9wst6a8vjc69r66y6fj70t5",
        "personName": "Mom"
      },
      "handle": "mom.wong.bkk",
      "input": "https://www.instagram.com/mom.wong.bkk/",
      "key": "c1",
      "platform": "instagram",
      "platformUserId": null,
      "profileUrl": "https://www.instagram.com/mom.wong.bkk/",
      "suggestedPersonId": null,
      "warnings": []
    },
    {
      "alternatives": [
        "x",
        "xiaohongshu"
      ],
      "avatarUrl": null,
      "confidence": "medium",
      "displayName": null,
      "existing": {
        "accountId": "acc_01j9te0skfktnnmw6zvew46azb",
        "personId": "per_01j9f8r1agkh6g3jp30xcwnytc",
        "personName": "Lin"
      },
      "handle": "lin.cooks",
      "input": "@lin.cooks",
      "key": "c2",
      "platform": "instagram",
      "platformUserId": null,
      "profileUrl": "https://www.instagram.com/lin.cooks/",
      "suggestedPersonId": null,
      "warnings": []
    },
    {
      "avatarUrl": null,
      "confidence": "high",
      "displayName": null,
      "existing": {
        "accountId": "acc_01j936xmqyft8qfbq7srt9h04r",
        "personId": "per_01j9yjkch7a0ayzz8784jtf08t",
        "personName": "Uncle Wei"
      },
      "handle": "MS4wLjABAAAAweichengdu0000000000000000000000",
      "input": "MS4wLjABAAAAweichengdu0000000000000000000000",
      "key": "c3",
      "platform": "douyin",
      "platformUserId": null,
      "profileUrl": "https://www.douyin.com/user/MS4wLjABAAAAweichengdu0000000000000000000000",
      "suggestedPersonId": null,
      "warnings": [
        "addWarningNeedsAgent"
      ]
    }
  ],
  "unrecognized": [
    "hello world"
  ]
}

400

Section titled “400”

Invalid request.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
i18nKey
string
detail
string
fields
Array<object>
object
path
required
string
code
required
string
i18nKey
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "i18nKey": "example",
  "detail": "example",
  "fields": [
    {
      "path": "example",
      "code": "example",
      "i18nKey": "example"
    }
  ]
}

429

Section titled “429”

Too many requests. See Retry-After.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
i18nKey
string
detail
string
fields
Array<object>
object
path
required
string
code
required
string
i18nKey
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "i18nKey": "example",
  "detail": "example",
  "fields": [
    {
      "path": "example",
      "code": "example",
      "i18nKey": "example"
    }
  ]
}

Headers

Section titled “Headers”
Retry-After
integer