---
title: "POST /v2/social-media"
method: POST
path: "/v2/social-media"
tags: ["Social Community"]
---

# POST /v2/social-media

`POST /v2/social-media`

## Request

- Base URL: `https://api.arbital.xyz` (the document declares no server; this is the origin it was published from)
- URL: `https://api.arbital.xyz/v2/social-media`
- Auth: HTTP bearer

Uploads one binary JPEG, PNG, still WebP or GIF, at most 15 MiB. The server validates and normalizes decoded content, strips metadata and approves every rendered GIF frame before storing it privately. Processing permits at most 16 million decoded pixels across at most 60 GIF frames. Scope is immutable; message uploads require the exact chat_id and current membership. An optional canonical Tenor URL is attribution only for GIFs and is never fetched. A 201 response contains approved metadata without an ordinal; use its id in media_ids on a supported parent write within 24 hours. Uploads remain disabled until the runtime write gate and storage/moderation providers are ready. No multipart, base64 JSON, remote URL ingestion, public URL or CDN access is supported. When CDN delivery is enabled, approved upload metadata can include short-lived viewer-specific delivery URLs and a WebP thumbnail. These capabilities are optional; access_path remains the authenticated fallback.

## Query parameters

- `scope` 'post' | 'post_reply' | 'asset_comment_reply' | 'message', required
- `chat_id` string, uuid
- `source_tenor_url` string

## Request body `image/jpeg`

- string, binary

## Response `201`

Approved private upload, ready for one atomic parent binding

- union: Approved normalized upload metadata. There is no ordinal until parent binding. Unattached uploads expire after 24 hours; only their uploader may preview them. Decoded work is bounded to 16 million pixels, including every rendered GIF frame, and at most 60 GIF frames. Authenticated HTTP responses may include short-lived CDN delivery and thumbnail URLs; access_path stays available when delivery is disabled or unavailable.
  - object
    - `id` string, uuid, required
    - `media_kind` 'image', required
    - `mime_type` 'image/jpeg' | 'image/png' | 'image/webp', required
    - `size_bytes` integer, required
    - `width` integer, required
    - `height` integer, required
    - `access_path` string, required: Authenticated relative byte-read path for this media ID; never a public or signed storage URL.
    - `delivery` SocialMediaDelivery: Optional HTTP-only delivery capability, issued after current access checks. URLs expire together at expires_at. Clients load the thumbnail in feeds and the full normalized image or animated GIF when opened. Refresh by re-reading the parent endpoint; access_path remains an authenticated fallback. Never persist, broadcast or share these viewer-specific URLs.
      - `url` string, uri, required: Short-lived Cloudflare Worker URL for the full normalized image or GIF. Treat it as opaque; refetch authorized parent metadata before expires_at to renew.
      - `expires_at` string, date-time, required
      - `thumbnail` object: Bounded WebP preview. Animated GIFs use an approved still poster.
        - `url` string, uri, required
        - `mime_type` 'image/webp', required
        - `size_bytes` integer, required
        - `width` integer, required
        - `height` integer, required
  - object
    - `id` string, uuid, required
    - `media_kind` 'gif', required
    - `mime_type` 'image/gif', required
    - `size_bytes` integer, required
    - `width` integer, required
    - `height` integer, required
    - `access_path` string, required: Authenticated relative byte-read path for this media ID; never a public or signed storage URL.
    - `source_tenor_url` string
    - `delivery` SocialMediaDelivery: Optional HTTP-only delivery capability, issued after current access checks. URLs expire together at expires_at. Clients load the thumbnail in feeds and the full normalized image or animated GIF when opened. Refresh by re-reading the parent endpoint; access_path remains an authenticated fallback. Never persist, broadcast or share these viewer-specific URLs.
      - `url` string, uri, required: Short-lived Cloudflare Worker URL for the full normalized image or GIF. Treat it as opaque; refetch authorized parent metadata before expires_at to renew.
      - `expires_at` string, date-time, required
      - `thumbnail` object: Bounded WebP preview. Animated GIFs use an approved still poster.
        - `url` string, uri, required
        - `mime_type` 'image/webp', required
        - `size_bytes` integer, required
        - `width` integer, required
        - `height` integer, required

## Other responses

- `400`: invalid_social_media: malformed scope, chat, attribution, type, dimensions or decoded content
- `401`: Authentication is missing or invalid
- `403`: social_restricted: the active account is restricted from social uploads
- `404`: social_media_not_found: inactive account or unavailable chat/current membership
- `408`: social_media_timeout: upload body or processing exceeded its deadline
- `413`: The binary body exceeds 15 MiB
- `422`: content_rejected: moderation rejected the normalized content or a rendered GIF frame
- `429`: social_rate_limited: the uploader's media budget is exhausted
- `503`: social_media_busy (retry after 1 second), social_media_disabled or social_media_unavailable; approval is never assumed after a provider failure

---

[API](https://skmtc.dev/arbital/apis/arbital-api.md) - [All operations](https://skmtc.dev/arbital/apis/arbital-api/llms.txt) - [OpenAPI document](https://skmtc.dev/arbital/apis/arbital-api/revisions/bb0185edf43a?raw)