Chatters client integration

Onlys owns the originals and authorization to download. Chatters retains its creator resource catalog, descriptions, classification, sale approval, and offers.

  1. The creator creates an Onlys key with vault:read and vault:links.
  2. An authorized Chatters workspace owner/admin connects it to the correct Chatters creator. Store the key encrypted on the backend with an external encryption key, and validate /me to confirm the Onlys account association.
  3. List all pages of ready assets. Store source=onlys, the stable asset ID and SHA-256 in resource metadata. Map image to Chatters photo, video to video; skip audio for its photo/video catalog. Preserve existing human descriptions, approval, prices, tags, and offer links during synchronization. New imports should start unapproved and unavailable for sale.
  4. Generate a managed link when an authorized Chatters workflow needs access. Keep credentials out of its extension and fan messages; share only the link.
  5. Persist link ID/expiry for revocation. Refresh the catalog periodically and mark removed or suspended sources unavailable. Do not replace unrelated catalog items with a partial page from Onlys.

The existing Chatters PUT /api/v1/creators/{id}/resources replaces the entire catalog. A client should merge the complete fetched inventory with existing resources before calling it, preserving Chatters approval decisions. Onlys API authentication and Chatters workspace authentication are independent.

PHP backend example

Resolution and duration are display metadata, not duplicate keys. Retain each Onlys asset ID separately even when files look similar. Dashboard visual groups are not exposed in API v1. Client-side grouping must not silently overwrite another resource's approval, price or description. The existing photo/video catalog example intentionally excludes audio; this is a client policy, not an Onlys API limitation.

function onlysRequest(string $key, string $method, string $path, ?array $body = null): array
{
    $ch = curl_init('https://onlys.vip/api/v1' . $path);
    $headers = ['Authorization: Bearer ' . $key, 'Accept: application/json'];
    if ($body !== null) $headers[] = 'Content-Type: application/json';
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_FOLLOWLOCATION => false,
        CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
    ]);
    if ($body !== null) curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body, JSON_THROW_ON_ERROR));
    $raw = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    if ($raw === false) throw new RuntimeException('Onlys transport failed');
    if ($status === 204) return [];
    $result = json_decode($raw, true, 32, JSON_THROW_ON_ERROR);
    if ($status < 200 || $status >= 300) {
        // Production: handle 429 Retry-After and 503 backoff, and retain request_id.
        throw new RuntimeException('Onlys HTTP ' . $status . ': ' . ($result['error']['code'] ?? 'unknown'));
    }
    return $result;
}

$identity = onlysRequest($key, 'GET', '/me')['data'];
$assets = []; $cursor = null;
do {
    $query = ['state' => 'ready', 'limit' => 100];
    if ($cursor !== null) $query['cursor'] = $cursor;
    $page = onlysRequest($key, 'GET', '/vault/assets?' . http_build_query($query));
    foreach ($page['data'] as $asset) {
        if (!$asset['suspended'] && in_array($asset['type'], ['image', 'video'], true)) $assets[] = $asset;
    }
    $cursor = $page['next_cursor'];
} while ($cursor !== null);

// After selecting an asset and authorizing the Chatters user:
$link = onlysRequest($key, 'POST', '/vault/assets/' . $assetId . '/links', [
    'variant' => 'original', 'mode' => 'managed', 'expires_in' => 86400,
])['data'];
// Deliver $link['url']; retain $link['id'] and $link['expires_at'].
onlysRequest($key, 'DELETE', '/vault/links/' . $link['id']);

The example does not send media, initiate a sale, or modify the Chatters catalog. Implement those actions through the existing Chatters authorization and approval workflow. Do not interpret a scanned/ready vault asset as approved for sale.