Sayyarat Documentation

Public Docs

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

Public surface

API Usage Guide

Purpose

This document is the public entry point for developers integrating with Sayyarat APIs.

Use it for:

  • where the live API docs are
  • which route family to build against
  • how auth works at a client level
  • which response patterns clients should expect

Live API References

  • Swagger UI: https://api.sayyarat.me/docs
  • ReDoc: https://api.sayyarat.me/redoc
  • OpenAPI schema: https://api.sayyarat.me/openapi.json

These reflect the running API service.

Route Family Rule

For new integrations, use /v1.

Examples:

  • GET /v1/listings
  • GET /v1/listings/{listing_ref}
  • POST /v1/auth/login
  • POST /v1/auth/native/login
  • GET /v1/auth/me
  • GET /v1/account/overview

Compatibility routes still exist for older browser flows, but they are not the default contract for new clients.

Auth Rule

Signed-in /v1 routes support two client patterns:

  • browser clients
    same-origin cookie session
  • native or non-browser clients
    bearer access token plus refresh flow

Clients should not invent their own auth behavior around older compatibility routes if an equivalent /v1 path exists.

For full auth behavior, see /auth-spec.

Public Catalog Rule

For public marketplace reads, use:

  • GET /v1/listings
  • GET /v1/listings/{listing_ref}

The durable public collection response is metadata plus items, not a bare array.

Seller API Rule

For signed-in seller and account work, prefer the /v1/account/* routes.

Current durable areas include:

  • auth and current-user reads
  • account overview and details
  • business memberships and business dashboard
  • listing creation and editing
  • listing lifecycle updates
  • listing media reads and upload flows
  • saved listings

Admin-only routes are internal staff surfaces and must not be treated as public integration routes.

Error Rule

API errors should be read from the structured detail object.

Clients should expect fields such as:

  • code
  • message
  • request_id
  • support_code
  • optional field_errors

When the API exposes a matching *_label field for a state value, clients should use that label for display instead of dumping the raw state value into UI.