Talkable Assets API

openapi: 3.0.3
info:
  title: Talkable Advocate Offers Assets API
  version: '2.0'
  contact:
    name: API Reference
    url: https://docs.talkable.com/api_v2/
servers:
- url: https://www.talkable.com
security:
- api_key: []
tags:
- name: Assets
paths:
  /api/v2/assets:
    get:
      summary: List assets
      tags:
      - Assets
      parameters:
      - $ref: '#/components/parameters/site_slug_in_query_required'
      - name: content_type
        in: query
        required: false
        description: Filter by content type or its prefix, e.g. `image` or `image/png`.
        schema:
          type: string
          example: image
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      operationId: listAssets
      responses:
        '200':
          description: assets list
          content:
            application/json:
              example:
                ok: true
                result:
                  assets:
                  - content_type: video/mp4
                    id: 3
                    name: frog_video_short.mp4
                    url: https://d2jjzw81hqbuqv.cloudfront.net/static_assets/files/3/original/frog_video_short.mp4
                    size: 281524
                    width: null
                    height: null
                    fingerprint: f773c1d7bd57e3549a8cd2516fdbdd4e
                    created_at: '2026-07-07T11:04:57.000-07:00'
                    updated_at: '2026-07-07T11:04:57.000-07:00'
                  - content_type: image/png
                    id: 2
                    name: closebutton.png
                    url: https://d2jjzw81hqbuqv.cloudfront.net/static_assets/files/2/original/closebutton.png
                    size: 6600
                    width: 100
                    height: 100
                    fingerprint: 0c406c68a263801c7ce983efda254268
                    created_at: '2026-07-07T11:04:57.000-07:00'
                    updated_at: '2026-07-07T11:04:57.000-07:00'
                  - content_type: image/jpeg
                    id: 1
                    name: santa.jpg
                    url: https://d2jjzw81hqbuqv.cloudfront.net/static_assets/files/1/original/santa.jpg
                    size: 121059
                    width: 960
                    height: 900
                    fingerprint: df262c29b6ab5f5a97b6870c3c9ba813
                    created_at: '2026-07-07T11:04:57.000-07:00'
                    updated_at: '2026-07-07T11:04:57.000-07:00'
                  total: 3
    post:
      summary: Upload an asset
      tags:
      - Assets
      parameters:
      - $ref: '#/components/parameters/site_slug_in_query_required'
      operationId: uploadAsset
      responses:
        '201':
          description: asset uploaded
          content:
            application/json:
              example:
                ok: true
                result:
                  asset:
                    content_type: image/jpeg
                    id: 1
                    name: santa.jpg
                    url: https://d2jjzw81hqbuqv.cloudfront.net/static_assets/files/1/original/santa.jpg
                    size: 121059
                    width: 960
                    height: 900
                    fingerprint: df262c29b6ab5f5a97b6870c3c9ba813
                    created_at: '2026-07-07T11:05:03.000-07:00'
                    updated_at: '2026-07-07T11:05:03.000-07:00'
        '422':
          description: asset with the same name already exists
          content:
            application/json:
              example:
                ok: false
                error_message: 'Validation failed: File name has already been taken'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Asset file. The asset name is derived from the uploaded file name. Fails if an asset with the same name already exists on the account.
              required:
              - file
        required: true
  /api/v2/assets/{id}:
    get:
      summary: Find an asset
      tags:
      - Assets
      parameters:
      - name: id
        in: path
        schema:
          type: integer
        required: true
      - $ref: '#/components/parameters/site_slug_in_query_required'
      operationId: findAsset
      responses:
        '200':
          description: asset found
          content:
            application/json:
              example:
                ok: true
                result:
                  asset:
                    content_type: image/jpeg
                    id: 1
                    name: santa.jpg
                    url: https://d2jjzw81hqbuqv.cloudfront.net/static_assets/files/1/original/santa.jpg
                    size: 121059
                    width: 960
                    height: 900
                    fingerprint: df262c29b6ab5f5a97b6870c3c9ba813
                    created_at: '2026-07-07T11:05:10.000-07:00'
                    updated_at: '2026-07-07T11:05:10.000-07:00'
        '400':
          description: asset not found
          content:
            application/json:
              example:
                ok: false
                error_message: No asset found by `id`.
components:
  parameters:
    site_slug_in_query_required:
      name: site_slug
      in: query
      required: true
      schema:
        type: string
      description: Your Talkable Site ID. You can get this from your Talkable dashboard after you log in and create a site.
      example: my-store
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      description: Please provide here your API key, you can find it in Site Settings -> API Integration -> API Key