createCapture

POST

/captures

curl --request POST \
  --url http://localhost:8080/api/v1/captures \
  --header 'Content-Type: application/json' \
  --cookie hs_session=<hs_session> \
  --data '{ "platform": "instagram", "accountId": "per_01j9x3k8m2q4r5s6t7v8w9y0z1", "pageUrl": "https://example.com", "title": "example", "mode": "passive", "runId": "per_01j9x3k8m2q4r5s6t7v8w9y0z1", "capturedAt": "2026-04-15T12:00:00Z", "extensionVersion": "example", "assets": [ { "url": "https://example.com", "kind": "image", "order": 1, "width": 1, "height": 1, "inViewport": true } ] }'

• Your Homestead (default port; replace with your address)

Step 1 of a capture. Registers the page and its asset list. Returns an upload token for this capture and the asset keys the server does not already have.

Authorizations

• cookieAuth
• bearerAuth

Request Body^required

Media typeapplication/json

object

platform

required

string

Allowed values: instagram facebook line wechat bluesky x douyin xiaohongshu truthsocial

accountId

required

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

pageUrl

required

string format: uri

title

string

<= 500 characters

mode

required

string

Allowed values: passive update

runId

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

capturedAt

required

string format: date-time

extensionVersion

required

string

assets

required

Array<object>

<= 80 items

object

url

required

string format: uri

kind

required

string

Allowed values: image video poster background

order

required

Position in DOM order.

integer

width

integer

height

integer

inViewport

boolean

Responses

201

Capture created.

Media typeapplication/json

object

captureId

required

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

uploadToken

required

Hsu_… token for the helper; this capture only.

string

uploadExpiresAt

required

string format: date-time

assets

required

Array<object>

object

key

required

SHA-1 hex of the URL.

string

url

required

string format: uri

needed

required

False when the server already has these bytes.

boolean

Examples

Exampleseed

Derived from fixtures/seed.json.

{
  "assets": [
    {
      "key": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4",
      "needed": true,
      "url": "https://scontent.example.com/v/t51/asset-a.jpg"
    },
    {
      "key": "b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5",
      "needed": false,
      "url": "https://scontent.example.com/v/t51/asset-b.jpg"
    },
    {
      "key": "c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f6",
      "needed": true,
      "url": "https://scontent.example.com/v/t51/asset-c.jpg"
    }
  ],
  "captureId": "cap_01j9a1b2c3d4e5f6g7h8j9k026",
  "uploadExpiresAt": "2026-10-17T09:10:00.000Z",
  "uploadToken": "hsu_demoUploadToken0123456789abcdef"
}

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"
    }
  ]
}

403

Role or scope does not allow this.

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"
    }
  ]
}

404

Not found.

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

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

Retry-After

integer