Sayyarat Documentation

Public Docs

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

Public surfaceapi-usage-guide.md

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.