# TensorSave

> Community-driven deal list for domains, VPS, dedicated servers and LLM API offers.
> Users submit offers (human-moderated), vote, rate (1-5 stars), discuss in threaded
> comment threads, bookmark deals and report expired/fake offers. Merchant identity
> can be admin-verified.

- Site: https://tensorsave.com
- Human docs (API/MCP reference): https://tensorsave.com/docs/api
- Machine docs: this file
- OpenAPI-style endpoint list: https://tensorsave.com/api/v1/offers (GET) is the best starting probe
- Sitemap: https://tensorsave.com/sitemap.xml

## How to consume offers (no auth)

GET https://tensorsave.com/api/v1/offers — paginated list. Query params:
  q (free text), type (DOMAIN|VPS|DEDICATED|LLM), sort (smart|newest|top|ending|comments),
  validity (ACTIVE|EXPIRED), minRam, minCores, region, gpu, minTokens, maxMult, page, pageSize...
  Response: {"data":[Offer...],"meta":{"total","page","pageSize","totalPages"}}
GET https://tensorsave.com/api/v1/offers/{slug} — one offer with full type-specific "spec" object.

Offer JSON shape (common): id, slug, title, summary, description(markdown), type,
vendorName, offerUrl, couponCode, priceOffer, priceRegular, currency, billingPeriod,
renewalSamePrice, freeTrialDays, requiresCreditCard, paymentGateways[], validUntil,
verified(admin-verified merchant), validity(ACTIVE|EXPIRED), voteScore, commentCount,
ratingAvg, ratingCount, hotScore, author{...}, spec{type-specific fields}.

## Authentication

All write operations need an identity. Two ways:
1. Bearer API key: "Authorization: Bearer bfl_..." (user creates keys at https://tensorsave.com/me/api-keys)
2. Browser session cookie (logged-in user)

Banned users are rejected. Rate limits apply per user (offers 5/h, comments 10/10min,
votes 60/min, reports 10/h).

## MCP endpoint (Model Context Protocol, Streamable HTTP, stateless)

POST https://tensorsave.com/api/mcp — JSON-RPC 2.0. Protocol version: 2025-03-26.
Handshake: method "initialize" -> notifications/initialized -> "tools/list" / "tools/call".
Optional "Authorization: Bearer bfl_..." header unlocks user-scoped tools.

Tools:
- search_offers(query?, type?, sort?, minRamGb?, minFreeTokens?, page?)  [public]
- get_offer(slug)                                                        [public]
- submit_offer(offer{...same schema as POST /api/v1/offers})             [auth]
- rate_offer(slug, value 0..5; 0 clears)                                 [auth]
- bookmark_offer(slug, bookmarked bool)                                  [auth]
- my_offers()                                                            [auth]
- get_me()                                                               [auth]

JSON-RPC example:
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_offers","arguments":{"type":"LLM"}}}
Tool results: {"content":[{"type":"text","text":"<JSON>"}]}

## REST write endpoints (Bearer key or session)

POST   https://tensorsave.com/api/v1/offers                              submit (goes to moderation)
PATCH  https://tensorsave.com/api/v1/offers/{slug}                       edit own (re-enters moderation)
DELETE https://tensorsave.com/api/v1/offers/{slug}                       delete own
POST   https://tensorsave.com/api/v1/offers/{slug}/vote                  {"value":1|-1}
POST   https://tensorsave.com/api/v1/offers/{slug}/rating                {"value":1..5} (0 clears)
POST   https://tensorsave.com/api/v1/offers/{slug}/bookmark              {"bookmarked":true|false}
POST   https://tensorsave.com/api/v1/offers/{slug}/report                {"type":"ENDED|FAKE|MISMATCH|OTHER","message"}
GET    https://tensorsave.com/api/v1/offers/{slug}/comments              thread
POST   https://tensorsave.com/api/v1/offers/{slug}/comments              {"body","parentId"?}
POST   https://tensorsave.com/api/v1/comments/{id}/like                  toggle like
PATCH  https://tensorsave.com/api/v1/comments/{id}                       {"body"} (author only)
GET    https://tensorsave.com/api/v1/me                                  profile
GET    https://tensorsave.com/api/v1/me/offers                           own offers (all states)
GET    https://tensorsave.com/api/v1/me/bookmarks via web page           https://tensorsave.com/me/bookmarks
GET    https://tensorsave.com/api/v1/me/notifications                    inbox
POST   https://tensorsave.com/api/v1/me/notifications                    mark all read
GET/POST https://tensorsave.com/api/v1/me/api-keys                        manage API keys (key shown once at creation)
POST   https://tensorsave.com/api/v1/admin/offer-action                  admin moderation {"offerId","action","reason"?}

Errors: {"error":{"code","message"}}; validation 422 + fieldErrors; 429 + Retry-After.

## Submission rules

validUntil is REQUIRED and at most 12 months ahead. New/edited offers enter a human
moderation queue before publication. Expired offers auto-unpublish from default lists.
External merchant links must not be modified except appending our referral params
(utm_source=blackfridaylist&utm_medium=deal&ref=<slug>).