AI control

Acquire AI locks in bulk

POST/v1/accounts/{account_id}/ai-locks/acquire

Marks each fan as currently handled by an AI in the Fansquare CRM, in a single call. Same semantics as the single-fan endpoint applied to the whole batch: without ttl_seconds the locks never expire (released only by the batch release), with ttl_seconds the request acquires and refreshes them (send it again before expiry to keep the batch active).

Required scopewrite:ai_locks

Rate limit120 requests per minute

curl -X POST 'https://api.fansquare.so/v1/accounts/c851d9d6-b90b-4958-aed2-2fdaa2fe21a3/ai-locks/acquire' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste" \
  -H "Content-Type: application/json" \
  -d '{
  "fan_ids": [
    "a6df8022-e509-4575-ad28-e29c2d1d42dc"
  ],
  "ttl_seconds": 300
}'

{
  "acquired": 1,
  "expires_at": "2026-10-12T21:19:00.000Z"
}

Parameters

Headers

Fansquare-Versionstringrequired
API version to pin. Accepts the mineral name or the release date of a version.

Path

account_idstringrequired
MYM account id (account.external_id in GET /v1/creators).
min length 1

Body

application/json

fan_idsarray of stringsrequired
MYM fan ids. 1 to 500 per call; duplicates are ignored.
format uuidmin items 1max items 500
ttl_secondsinteger
Optional lock lifetime in seconds, applied to every fan in the batch. Omit it for locks that never expire (released only by the batch release). When set, send the request again before expiry to keep the locks active.
min 30max 86400

Response

OK, application/json

acquiredintegerrequired
Number of distinct fans locked in this call.
expires_atstring | nullrequired
When the locks of the batch expire (ISO 8601), or null when they never expire.
format date-time

curl -X POST 'https://api.fansquare.so/v1/accounts/c851d9d6-b90b-4958-aed2-2fdaa2fe21a3/ai-locks/acquire' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste" \
  -H "Content-Type: application/json" \
  -d '{
  "fan_ids": [
    "a6df8022-e509-4575-ad28-e29c2d1d42dc"
  ],
  "ttl_seconds": 300
}'

{
  "acquired": 1,
  "expires_at": "2026-10-12T21:19:00.000Z"
}