DSTORE PUBLISHER API
====================
Version 1. Documentation optimized for LLM agents and humans.

Short discovery file: https://s.f2p.ms/llms.txt
This document:        https://s.f2p.ms/api.txt
UI aliases:           https://s.f2p.ms/agent  ·  https://s.f2p.ms/agent.txt

MENTAL MODEL
------------
dStore is a decentralised app catalog (PWA / websites / store links).
Each catalog entry has a numeric sid (store id).
Adding a URL creates or updates a card; the server audits metadata,
icon, screenshots and AI fields asynchronously.

Authors and agents can:
  1. SUBMIT a URL into the catalog (public, rate-limited).
  2. READ a card as HTML page or machine-readable JSON.
  3. READ a public collection (list) as JSON.

Typical agent flow after building/shipping a product:
  GET ?add=<product_url>  →  note sid  →  poll /{sid}.json until title/icon ready
  →  open /{sid} to verify the card.

BASE URLS
---------
Storefront (this host):  https://s.f2p.ms
API / add endpoint:      https://db.dstore.one
CDN icons/screens:       https://cdn.dstore.one
Discovery (llms.txt):    https://s.f2p.ms/llms.txt
This guide (api.txt):    https://s.f2p.ms/api.txt
UI aliases:              https://s.f2p.ms/agent , https://s.f2p.ms/agent.txt

No API token is required for public add/read.
All JSON responses use UTF-8.

1. SUBMIT A URL
---------------
Preferred (explicit query):
  GET https://db.dstore.one/?add=https%3A%2F%2Fexample.com
  GET https://s.f2p.ms/?add=https%3A%2F%2Fexample.com

Also accepted:
  GET https://db.dstore.one/https://example.com
  GET https://s.f2p.ms/https://example.com

Encode the URL. Prefer https://. www. is normalized away.
Play Store / App Store / Telegram / IMDb / Kinopoisk links are supported.

curl example:
  curl -sS "https://db.dstore.one/?add=https%3A%2F%2Fexample.com"

Success JSON (examples):
  {"status":"new","sid":12345,"id":"..."}      — created, audit queued
  {"status":"exist","sid":12345,"id":"..."}    — already in catalog
  {"status":"update","sid":12345,"id":"..."}   — found, refresh scheduled

Errors:
  {"status":0,"error":"invalid_url","reason":"..."}
  HTTP 429 {"status":0,"error":"rate_limit","retry_after":N,"limit":20}

Default rate limit: ~20 adds per IP per hour (ADD_RATE_LIMIT_PER_HOUR).
Be moderate: spammy bulk submits may be blocked.

After status=new the card may be incomplete for 30–120+ seconds while
audit / icon / AI enrichment finish. Poll JSON (below) instead of re-adding.

2. READ A CARD (HTML)
---------------------
  https://s.f2p.ms/{sid}
Example: https://s.f2p.ms/12345

Human UI. Good for a final visual check.

3. READ A CARD (JSON) — preferred for agents
---------------------------------------------
  GET https://s.f2p.ms/{sid}.json
  GET https://db.dstore.one/{sid}.json

curl example:
  curl -sS "https://s.f2p.ms/12345.json"

Pretty-printed JSON. Useful fields typically include:
  id / sid, title, subtitle, description, url, icon,
  screenshots / screenCdn, tags, ranks, store links, similar apps.

Not found: HTTP 404 {"error":"not_found","sid":...}
Rate limited: HTTP 429 {"error":"rate_limit","retry_after":N}

Polling tip after add:
  every 5–10s for up to ~3 minutes until title and icon are non-empty.
Do not call ?add= again for the same URL while waiting.

4. PUBLIC COLLECTIONS (LISTS)
-----------------------------
HTML page:  https://s.f2p.ms/list/{listRef}
JSON:       https://s.f2p.ms/list/{listRef}.json

listRef is the public collection id/slug from a share URL.
JSON includes collection meta and apps with direct site links.

5. SEARCH (UI / SOCKET)
-----------------------
Interactive semantic search lives in the SPA Search tab.
There is no stable public REST search for agents yet — prefer
direct sid / URL add, or open https://s.f2p.ms and use Search.

6. QUICK LINKS
--------------
GitHub:     https://s.f2p.ms/git
Dev chat:   https://s.f2p.ms/chat
llms.txt:   https://s.f2p.ms/llms.txt
api.txt:    https://s.f2p.ms/api.txt
Agent UI:   https://s.f2p.ms/agent

RULES
-----
- Submit only real product / app / useful web URLs you control or represent.
- Do not scrape private data; catalog cards are public by design.
- Prefer one canonical URL per product (https apex or official store URL).
- If exist/update — reuse sid; do not create duplicates via URL variants.

Questions: use Dev Chat (https://s.f2p.ms/chat) or GitHub issues via /git.