Rowix Gifs API

openapi: 3.2.0
info:
  title: GifSnap GIF Search Gifs API
  version: 1.0.0
  description: Read-only search, trending, and GIF lookup endpoints. This description covers the current public, best-effort API, which does not require an API key. No SLA or unlimited-capacity commitment is made. Media URLs may use external CDNs and formats such as GIF or WebP; use returned URLs unchanged. Software package licensing does not grant rights to media. The additional For You recommendation endpoints use a gated public pilot with verified media and integration acceptance; live /recommendations/capabilities is authoritative. Physical-iPhone checks remain deferred and untested. See https://gifsnap.com/docs/for-you.md.
servers:
- url: https://gifsnap.com/api/v1
security: []
tags:
- name: Gifs
paths:
  /gifs/search:
    get:
      operationId: searchGifs
      summary: Search gifs
      parameters:
      - name: q
        in: query
        required: true
        description: A non-empty search phrase. URL-encode query parameters.
        schema:
          type: string
          minLength: 1
      - name: page
        in: query
        description: One-based page number. Pass a positive base-10 integer. Malformed or unsafe pagination returns HTTP 400.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: Results per page, from 1 to 50. Positive integer values above 50 retain the existing cap of 50; malformed values return HTTP 400.
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 25
      responses:
        '200':
          description: Media results with pagination. Empty data is a valid result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaPage'
        '503':
          description: Request could not be completed. Read the error message and show a recoverable state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Missing or empty q (search only), invalid page or limit, or pagination beyond the safe integer range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Gifs
  /gifs/trending:
    get:
      operationId: trendingGifs
      summary: Trending gifs
      parameters:
      - name: page
        in: query
        description: One-based page number. Pass a positive base-10 integer. Malformed or unsafe pagination returns HTTP 400.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: Results per page, from 1 to 50. Positive integer values above 50 retain the existing cap of 50; malformed values return HTTP 400.
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 25
      responses:
        '200':
          description: Media results with pagination. Empty data is a valid result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaPage'
        '503':
          description: Request could not be completed. Read the error message and show a recoverable state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Missing or empty q (search only), invalid page or limit, or pagination beyond the safe integer range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Gifs
  /gifs/{id}:
    get:
      operationId: getGif
      summary: Read a GIF by its catalog ID
      description: Use an id returned by search or trending. Do not construct IDs from media URLs.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: One GIF object, without a data wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gif'
        '404':
          description: GIF not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Request could not be completed. Read the error message and show a recoverable state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Gifs
  /gifs/for-you:
    post:
      summary: Rank an anonymous session using a bounded taste snapshot
      description: 'Session ID is a random UUID per feed opening, never a user ID. Apply favorites > confirmed sends > recent selection; selections may have been cancelled. Preferences include capped recent save/send/skip feedback retained locally after acknowledgements. Exclude all supplied content IDs, preserve cursor session/exclusion state, deduplicate visual alternate encodings, diversify reaction/style clusters and reserve an initial 10–15% exploration experiment. Resolve seed URLs only by exact lookup in your own indexed catalog; NEVER fetch arbitrary supplied URLs. Use verified canonical content_id, eligibility and provider attribution. Echo only original sending URL, while poster_url and MP4 playback.url must be on media.gifsnap.com or gifsnap.com. No external provider fallback pool without ranking/display rights. next_cursor:null ends the feed. Stable cursors must not repeat pages. Mint feedback_token bound to session, request, model, recommendation IDs/content IDs; position is the client-rendered ordinal (join recommendation_id to the original server rank), valid for the seven-day offline event window; prevent client-fabricated exposures from polluting training. Limit request body 1 MiB and response 512 KiB. No client-side credentials/cookies required: rate limit public sessions and treat all client feedback as untrusted analytics, never billing authority.'
      responses:
        '200':
          description: Success; application/json, no redirect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForYouPage'
        '429':
          description: Rate limited; preserve pending client state
          headers:
            Retry-After:
              schema:
                type: integer
        '503':
          description: Unavailable; client retains Search and pending feedback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForYouRequest'
      tags:
      - Gifs
      operationId: postGifsForYou
      x-operation-id-source: derived
components:
  schemas:
    ForYouSeedIdentity:
      type: object
      additionalProperties: false
      properties:
        provider:
          enum:
          - gifsnap
          - giphy
          - klipy
        id:
          type: string
          minLength: 1
          maxLength: 256
        content_id:
          type: string
          minLength: 1
          maxLength: 256
        source:
          type: string
          minLength: 1
          maxLength: 100
      required:
      - provider
      - id
    ForYouSeed:
      type: object
      additionalProperties: false
      properties:
        url:
          type: string
          minLength: 1
          maxLength: 4096
          format: uri
          pattern: ^https://
        identity:
          $ref: '#/components/schemas/ForYouSeedIdentity'
        signal:
          enum:
          - favorite
          - confirmedSend
          - recentSelection
        occurred_at:
          type: string
          format: date-time
      required:
      - url
      - signal
    ForYouIdentity:
      type: object
      additionalProperties: false
      properties:
        provider:
          const: gifsnap
        id:
          type: string
          minLength: 1
          maxLength: 256
        content_id:
          type: string
          minLength: 1
          maxLength: 256
        source:
          type: string
          minLength: 1
          maxLength: 100
      required:
      - provider
      - id
      - content_id
    MediaPage:
      type: object
      required:
      - data
      - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Gif'
        pagination:
          $ref: '#/components/schemas/Pagination'
        query:
          type: string
    ForYouPage:
      type: object
      additionalProperties: false
      properties:
        contract_version:
          const: 1
        request_id:
          type: string
          minLength: 1
          maxLength: 200
        model_version:
          type: string
          minLength: 1
          maxLength: 100
        feedback_token:
          type: string
          minLength: 1
          maxLength: 4096
        items:
          type: array
          items:
            $ref: '#/components/schemas/ForYouItem'
          maxItems: 30
        next_cursor:
          type:
          - string
          - 'null'
          maxLength: 2048
      required:
      - contract_version
      - request_id
      - model_version
      - feedback_token
      - items
      - next_cursor
    ForYouRequest:
      type: object
      additionalProperties: false
      properties:
        contract_version:
          const: 1
        session_id:
          type: string
          minLength: 1
          maxLength: 200
        cursor:
          type:
          - string
          - 'null'
          maxLength: 2048
        limit:
          type: integer
          minimum: 1
          maximum: 12
        language:
          type: string
          minLength: 1
          maxLength: 100
        seeds:
          type: array
          items:
            $ref: '#/components/schemas/ForYouSeed'
          maxItems: 100
        excluded_content_ids:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 256
          maxItems: 10000
          description: 'Up to 10,000 exact catalog content IDs when the same API origin advertises X-GifSnap-Exclusion-Limit: 10000 on a successful capabilities or page response. Older clients and servers retain 1,500. The complete UTF-8 JSON request remains limited to 1 MiB. Preserve account-local hidden/viewed history; do not clear it or send account identity. The service unions exclusions within an anonymous session up to 20,000 and never truncates that union.'
        preferences:
          type: array
          items:
            $ref: '#/components/schemas/ForYouPreference'
          maxItems: 100
      required:
      - contract_version
      - session_id
      - limit
      - language
      - seeds
      - excluded_content_ids
      - preferences
    Pagination:
      type: object
      required:
      - page
      - limit
      - total
      - has_next
      - next_page
      - offset
      properties:
        page:
          type: integer
          minimum: 1
        limit:
          type: integer
          minimum: 1
          maximum: 50
        total:
          type: number
          minimum: 0
          description: Upstream result count when supplied; otherwise an estimate from the current offset and batch. It may change between requests. Follow has_next and next_page instead of deriving continuation from total.
        has_next:
          type: boolean
        next_page:
          type:
          - integer
          - 'null'
          minimum: 1
        offset:
          type: integer
          minimum: 0
    Gif:
      type: object
      required:
      - id
      - title
      - url
      - preview_url
      - width
      - height
      - type
      properties:
        id:
          type: string
        title:
          type: string
        url:
          type: string
          format: uri
          description: Full media URL. Keep for sending, sharing and full-quality playback; use returned URLs unchanged.
        preview_url:
          type: string
          format: uri
          description: Poster or legacy preview, which can be static. Do not assume this URL is animated.
        width:
          type: number
          minimum: 0
        height:
          type: number
          minimum: 0
        type:
          type: string
          enum:
          - gif
          - sticker
        source:
          type: string
          description: Provider metadata returned by the catalog.
        created_at:
          type: string
        content_id:
          type: string
          description: Optional verified provider identity shared by known alternate encodings of the same item. Use for presentation deduplication when present; preserve the original id for lookups.
        animated_preview:
          $ref: '#/components/schemas/AnimatedPreview'
    AnimatedPreview:
      type: object
      description: Optional verified small animation for picker grids. Use only when the renderer supports mime_type; fall back to the full url if absent or loading fails. Do not replace the selected item full url with this preview.
      required:
      - url
      - mime_type
      - width
      - height
      - animated
      properties:
        url:
          type: string
          format: uri
        mime_type:
          type: string
          enum:
          - image/gif
          - image/webp
          - video/mp4
          - video/webm
        width:
          type: integer
          minimum: 1
          maximum: 480
        height:
          type: integer
          minimum: 1
          maximum: 480
        byte_size:
          type: integer
          minimum: 1
          maximum: 524288
        animated:
          type: boolean
          const: true
    ForYouPreference:
      type: object
      additionalProperties: false
      properties:
        content_id:
          type: string
          minLength: 1
          maxLength: 256
        signal:
          enum:
          - save
          - unsave
          - confirmedSend
          - shareCompleted
          - quickSkip
          - notInterested
        occurred_at:
          type: string
          format: date-time
      required:
      - content_id
      - signal
      - occurred_at
    Error:
      type: object
      properties:
        error:
          type: string
        data:
          type: array
        pagination:
          type:
          - object
          - 'null'
    ForYouItem:
      type: object
      additionalProperties: false
      properties:
        recommendation_id:
          type: string
          minLength: 1
          maxLength: 200
        identity:
          $ref: '#/components/schemas/ForYouIdentity'
        title:
          type: string
          maxLength: 500
        url:
          type: string
          minLength: 1
          maxLength: 4096
          format: uri
          pattern: ^https://
        poster_url:
          type: string
          minLength: 1
          maxLength: 4096
          format: uri
          pattern: ^https://
        width:
          type: integer
          minimum: 1
          maximum: 4096
        height:
          type: integer
          minimum: 1
          maximum: 4096
        playback:
          $ref: '#/components/schemas/ForYouPlayback'
        personalization_allowed:
          const: true
        attribution:
          type: string
          minLength: 1
          maxLength: 200
      required:
      - recommendation_id
      - identity
      - title
      - url
      - poster_url
      - width
      - height
      - playback
      - personalization_allowed
      - attribution
    ForYouPlayback:
      type: object
      additionalProperties: false
      properties:
        url:
          type: string
          minLength: 1
          maxLength: 4096
          format: uri
          pattern: ^https://
        mime_type:
          const: video/mp4
        width:
          type: integer
          minimum: 1
          maximum: 1280
        height:
          type: integer
          minimum: 1
          maximum: 1280
        byte_size:
          type: integer
          minimum: 1
          maximum: 8388608
        duration_ms:
          type: integer
          minimum: 200
          maximum: 30000
      required:
      - url
      - mime_type
      - width
      - height
      - byte_size
      - duration_ms
externalDocs:
  description: GifSnap SDK quickstarts and API integration reference
  url: https://gifsnap.com/docs
x-for-you-rollout:
  enabled: false
  documentation: https://gifsnap.com/docs/for-you.md
  contract: https://gifsnap.com/for-you.openapi.json
  enable_only_after: Real DripChat integration acceptance and verified eligible multimodal media pool