# Sefid for developers and agents

Sefid is an AI sales and support chatbot for online stores. It learns a store's own site and products and answers only from them. Site: https://sefid.dev (the pages are in Persian; every page is also served as markdown when you send `Accept: text/markdown`).

## Machine-readable documents

- API catalog (RFC 9727): https://sefid.dev/.well-known/api-catalog
- OpenAPI: https://sefid.dev/openapi.json
- MCP server card: https://sefid.dev/.well-known/mcp/server-card.json (panel: https://sefid.dev/.well-known/mcp/panel-server-card.json)
- Agent skills: https://sefid.dev/.well-known/agent-skills/index.json
- ai-catalog (ARD): https://sefid.dev/.well-known/ai-catalog.json
- OAuth: https://sefid.dev/.well-known/oauth-authorization-server and https://sefid.dev/.well-known/oauth-protected-resource
- Overview for language models: https://sefid.dev/llms.txt

## MCP servers

- Public, no sign-in: `https://sefid.dev/api/mcp`. Tools: `sefid_overview`, `sefid_read_page`, `sefid_plans`.
- Panel, OAuth (`sefid.read`, read-only): `https://sefid.dev/api/mcp/panel`. Tools: `my_site`, `my_open_requests`, `my_recent_conversations`. How to get a token: https://sefid.dev/auth.md

Both speak MCP Streamable HTTP: JSON-RPC 2.0, one message per POST, plain JSON replies, no event stream.

## Store API (server to server)

A store's own server pushes products, order states and notices to Sefid with HMAC-signed requests (the API is switched on per site by the Sefid team):

- `POST /api/ingest/products` upsert `{"products": [{"externalId", "name", "price", …}]}`
- `DELETE /api/ingest/products/{externalId}`
- `POST /api/ingest/order-status` `{"externalOrderId", "status", "phone" | "email", "trackingCode", …}`
- `POST /api/ingest/notify` `{"title", "phone" | "email", "link"}`
- `POST /api/ingest/verify` checks the keys

Headers: `X-Sefid-Key` (public key), `X-Sefid-Timestamp` (unix ms, ±5 minutes), `X-Sefid-Nonce` (single use), `X-Sefid-Signature` = HMAC-SHA256 hex with the site's secret key of `METHOD\nPATH\nTIMESTAMP\nNONCE\nsha256hex(BODY)`. The secret key never goes to a browser.

## Installing the chat on a site

One line before `</body>`, with the site's id from the Sefid panel (Install page):

```html
<script src="https://sefid.dev/api/widget/loader.js" data-sefid-id="S-XXXXXXXXX" async></script>
```

WordPress / WooCommerce: the Sefid plugin (https://sefid.dev/woocommerce/) installs the chat and keeps products in sync with no code.
