SocialClaw Assets and Media Delivery API

openapi: 3.2.0
info:
  title: SocialClaw Assets and Media Delivery API
  version: 1.0.0
  description: Complete SocialClaw API reference for social account connections, media uploads, validation, scheduling, publishing, analytics, dashboard APIs, webhooks, and delivery URLs.
servers:
- url: https://getsocialclaw.com
  description: SocialClaw production API
security:
- BearerAuth: []
tags:
- name: Assets and Media Delivery
  description: Upload, register, delete, and deliver SocialClaw-managed media.
paths:
  /v1/assets:
    get:
      tags:
      - Assets and Media Delivery
      operationId: get_v1_assets
      summary: List assets
      description: Lists uploaded media in the workspace, newest first. Each asset includes a publicUrl reusable as media_link.
      security:
      - BearerAuth: []
      parameters:
      - name: query
        in: query
        required: false
        schema:
          type: string
        description: Text match over filename, id, kind, mime, or url. Also accepted as q.
      - name: kind
        in: query
        required: false
        schema:
          type: string
        description: 'Filter by media kind: image or video.'
      - name: mime
        in: query
        required: false
        schema:
          type: string
        description: Mime prefix filter, e.g. video/mp4. Also accepted as mimeType.
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Created lower bound. Also accepted as createdFrom.
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Created upper bound. Also accepted as createdTo.
      - name: sort
        in: query
        required: false
        schema:
          type: string
        description: created_desc (default) or created_asc.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 48
        description: Maximum assets to return. Defaults to 24, capped at 48.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetsResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
    post:
      tags:
      - Assets and Media Delivery
      operationId: post_v1_assets
      summary: Register asset
      description: Registers an existing object or externally managed asset in the workspace.
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetRegistrationRequest'
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /v1/assets/upload:
    post:
      tags:
      - Assets and Media Delivery
      operationId: post_v1_assets_upload
      summary: Upload asset
      description: 'Uploads a small media file as base64 and returns a SocialClaw delivery URL.


        Note: Use POST /v1/assets/import for anything large: it takes a URL instead of base64 and handles files up to 1 GB.'
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetUploadRequest'
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /v1/assets/import:
    post:
      tags:
      - Assets and Media Delivery
      operationId: post_v1_assets_import
      summary: Import asset from URL
      description: 'Downloads an image or video from a public URL into the media library. Returns 201 with a ready asset when the import finishes within about 40 seconds, otherwise 202 with status uploading while it continues in the background.


        Note: On 202, poll GET /v1/assets/{assetId} until status is ready before using publicUrl as media_link. A failed import reports status failed with an error message.


        Note: Files up to 1 GB. The URL must be a direct link to the file, not a web page.'
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetImportRequest'
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /v1/assets/{assetId}:
    get:
      tags:
      - Assets and Media Delivery
      operationId: get_v1_assets_assetId
      summary: Get asset
      description: Returns one asset with its status (uploading, ready, or failed) and, for running imports, importProgress.
      security:
      - BearerAuth: []
      parameters:
      - name: assetId
        in: path
        required: true
        schema:
          type: string
        description: Asset id.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
    delete:
      tags:
      - Assets and Media Delivery
      operationId: delete_v1_assets_assetId
      summary: Delete asset
      description: Marks an asset for deletion after the retention window.
      security:
      - BearerAuth: []
      parameters:
      - name: assetId
        in: path
        required: true
        schema:
          type: string
        description: Asset id.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OkResponse'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, or unauthorized credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or semantic validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-socialclaw-auth: bearer
      x-socialclaw-surface: public
  /media/{assetId}/{deliveryToken}/{filename}:
    get:
      tags:
      - Assets and Media Delivery
      operationId: get_media_assetId_deliveryToken_filename
      summary: Fetch media asset
      description: 'Streams a public media asset by delivery URL.


        Note: HEAD is also supported for metadata checks.'
      security: []
      parameters:
      - name: assetId
        in: path
        required: true
        schema:
          type: string
        description: Asset id.
      - name: deliveryToken
        in: path
        required: true
        schema:
          type: string
        description: Delivery token.
      - name: filename
        in: path
        required: true
        schema:
          type: string
        description: File name.
      responses:
        '200':
          description: Successful response.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
      x-socialclaw-auth: media
      x-socialclaw-surface: media
  /media/{assetId}/{deliveryToken}/previews/{filename}:
    get:
      tags:
      - Assets and Media Delivery
      operationId: get_media_assetId_deliveryToken_previews_filename
      summary: Fetch media preview
      description: 'Streams a generated thumbnail, poster, or preview asset.


        Note: HEAD is also supported for metadata checks.'
      security: []
      parameters:
      - name: assetId
        in: path
        required: true
        schema:
          type: string
        description: Asset id.
      - name: deliveryToken
        in: path
        required: true
        schema:
          type: string
        description: Delivery token.
      - name: filename
        in: path
        required: true
        schema:
          type: string
        description: Preview file name.
      responses:
        '200':
          description: Successful response.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
      x-socialclaw-auth: media
      x-socialclaw-surface: media
components:
  schemas:
    AssetResponse:
      type: object
      description: Single asset response.
      additionalProperties: false
      properties:
        ok:
          const: true
        asset:
          $ref: '#/components/schemas/Asset'
      required:
      - ok
      - asset
    AssetUploadRequest:
      type: object
      description: Base64 upload request for small media files.
      additionalProperties: true
      properties:
        filename:
          type: string
          description: Original file name.
        name:
          type:
          - string
          - 'null'
          description: Alias for filename.
        mime:
          type:
          - string
          - 'null'
          description: MIME type. Inferred from filename when omitted.
        contentBase64:
          type: string
          description: Base64-encoded file content.
        content_base64:
          type:
          - string
          - 'null'
          description: Snake-case alias for contentBase64.
        duration:
          type:
          - number
          - 'null'
        width:
          type:
          - integer
          - 'null'
        height:
          type:
          - integer
          - 'null'
        deleteAfter:
          type:
          - string
          - 'null'
          description: Optional retention timestamp.
          format: date-time
      required:
      - filename
      - contentBase64
    Asset:
      type: object
      description: SocialClaw-managed media asset.
      additionalProperties: true
      properties:
        id:
          type: string
          description: Asset id.
        tenantId:
          type:
          - string
          - 'null'
          description: Workspace id.
        storage:
          type:
          - string
          - 'null'
          description: Storage driver.
        objectKey:
          type:
          - string
          - 'null'
          description: Internal object key.
        originalFilename:
          type:
          - string
          - 'null'
          description: Original file name.
        mime:
          type: string
          description: MIME type.
        kind:
          type: string
          enum:
          - image
          - video
          - audio
          - other
        size:
          type: integer
          description: Size in bytes.
        status:
          type:
          - string
          - 'null'
          description: ready, uploading, draft, pending_delete, or provider-specific state.
        publicUrl:
          type:
          - string
          - 'null'
          description: Public delivery URL.
          format: uri
        preview:
          type:
          - object
          - 'null'
          description: Thumbnail, poster, or preview URLs.
        createdAt:
          type:
          - string
          - 'null'
          description: Creation time.
          format: date-time
      required:
      - id
      - mime
      - kind
    OkResponse:
      type: object
      description: Generic successful response.
      additionalProperties: true
      properties:
        ok:
          const: true
          description: Always true for successful JSON API responses.
      required:
      - ok
    AssetImportRequest:
      type: object
      description: Imports media from a public URL. The server streams the file straight into storage.
      additionalProperties: true
      properties:
        sourceUrl:
          type: string
          description: Direct public http(s) URL of the image or video file.
        filename:
          type:
          - string
          - 'null'
          description: Optional file name with extension. Inferred from the URL or Content-Type when omitted.
      required:
      - sourceUrl
    AssetsResponse:
      type: object
      description: Asset list response.
      additionalProperties: true
      properties:
        ok:
          const: true
        total:
          type: integer
          description: Total matching assets.
        limit:
          type: integer
          description: Page limit.
        offset:
          type: integer
          description: Page offset.
        assets:
          type: array
          description: Assets.
          items:
            $ref: '#/components/schemas/Asset'
      required:
      - ok
      - assets
    AssetRegistrationRequest:
      type: object
      description: Registers an already-stored asset or externally managed object for the workspace.
      additionalProperties: true
      properties:
        objectKey:
          type: string
          description: Storage object key.
        originalFilename:
          type:
          - string
          - 'null'
          description: Original filename. Also accepted as filename.
        publicUrl:
          type:
          - string
          - 'null'
          description: Public URL if already available.
        mime:
          type:
          - string
          - 'null'
          description: MIME type.
        kind:
          type:
          - string
          - 'null'
          enum:
          - image
          - video
          - audio
          - other
          - null
        size:
          type:
          - integer
          - 'null'
        status:
          type:
          - string
          - 'null'
          description: Asset status. Defaults to draft.
      required:
      - objectKey
    ErrorResponse:
      type: object
      description: Standard error response returned by JSON API routes.
      additionalProperties: false
      properties:
        ok:
          const: false
          description: Always false for errors.
        code:
          type:
          - string
          - 'null'
          description: Stable machine-readable error code.
        message:
          type: string
          description: Human-readable error message.
        details:
          type:
          - object
          - array
          - string
          - number
          - boolean
          - 'null'
          description: Optional route-specific details.
      required:
      - ok
      - message
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: SocialClaw API key
    DashboardSession:
      type: apiKey
      in: cookie
      name: socialclaw_dash_session
    WebhookSignature:
      type: apiKey
      in: header
      name: x-signature
externalDocs:
  description: Human-readable SocialClaw API documentation.
  url: https://getsocialclaw.com/docs/api
x-provenance:
  method: harvested
  publisher: SocialClaw
  source: https://getsocialclaw.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)