Sayyarat Documentation

Public Docs

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

Public surfacemedia-spec.md

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.

Current live rules include:

  • allowed types: image/jpeg, image/png, image/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