Sayyarat Documentation

Public Docs

Client-safe integration guidance for API usage, auth, listing lifecycle, media, and search.

Public surface

Media Specification

Purpose

This document defines the client-facing media contract for listing photos.

It covers:

  • upload flow from a client point of view
  • media states a client must handle
  • public photo-read behavior
  • validation rules exposed by the API

It does not expose internal storage or processing implementation.

Client Upload Flow

The client-facing upload flow is:

  1. ask the API for upload intent for a listing
  2. upload the file using the API-issued upload details
  3. call upload completion on the API
  4. refresh media state from the API

Client rules:

  • the client must not invent object keys
  • the client must not treat local upload completion as final readiness
  • the API remains the source of truth for media status

Media States

Clients must handle these states cleanly:

  • pending_upload
  • uploaded
  • processing
  • ready
  • failed
  • rejected

Only ready media should be treated as normal usable gallery media.

Public Photo Summary

Public listing payloads expose photo_summary for quick client use.

Clients should use:

  • photo_summary.total_count
  • photo_summary.ready_count
  • photo_summary.categories

Use the gallery-oriented payload for the full photo experience.

Upload Rules

The API publishes current upload rules through:

  • GET /v1/meta/media-rules

Clients should read those rules from the API instead of hardcoding them.

The live numeric limits in that route come from the DB-backed site-policy layer.

Current live defaults include:

  • allowed source types: image/heic, image/heif, image/jpeg, image/png, image/webp
  • gallery and listing-display variants are normalized to WebP
  • max uploaded at once: 5
  • max per listing: 150
  • max file size: 20 MB
  • minimum size: 1280 x 960

If those rules change, the API is authoritative.

Media Routes

Current durable seller-media routes include:

  • upload intent
  • batch upload intents
  • upload completion
  • batch completion
  • media update
  • batch media update

Exact request and response schemas should be read from the live API docs.

Client Display Rule

Clients should not guess variant names, gallery readiness, or review outcomes.

Use the API payload for:

  • ready media selection
  • cover image behavior
  • category display
  • review and safety labels when present