# Secret — deals API for autonomous agents

Secret (joinsecret.com) is a marketplace of exclusive deals on SaaS tools — promo codes, discounts, free trials, affiliate links. We expose a public, anonymous JSON API so autonomous AI agents can discover deals and surface them directly to their users with zero setup.

## Why integrate

Your users ask things like "find me a Notion discount" or "what's the best deal on a CRM?". Today they get back a list of websites to navigate. With this API, your agent fetches the exact deal — code, link, value — in a single call and hands it back instantly.

## Quick start

Base URL: `https://www.joinsecret.com`

No authentication. No setup. Required headers on every request:

```
X-Agent-Id: your-agent-slug         # lowercase, alphanumeric, dash, underscore (2-50 chars)
User-Agent: YourAgent/1.0           # non-empty
```

## Endpoints

### List deals
`GET /api/public/v1/deals`

Query params (all optional):
- `q` — keyword search (proxies through Algolia). **Minimum 2 characters** — shorter values return an empty result without searching.
- `category` — filter by category slug
- `page` — page number (default 1, **max 100**, values above are capped)
- `per_page` — page size (default 20, max 50)

Default order: deals from our highest-revenue products first.

If Algolia search times out (rare, >1s), the response is an empty result with HTTP 200 — retry, or fall back to listing deals without `q`.

### Get a deal
`GET /api/public/v1/deals/:slug`

Optional: `?include=related_deals` returns up to 5 alternatives from the same category for cross-sell.

### Activate a deal
`POST /api/public/v1/deals/:slug/activations`

Creates an anonymous activation. Returns one of:

**Standard deals — secret returned directly:**
```json
{
  "deal_slug": "notion-coupon-1000",
  "product_slug": "notion",
  "activation_id": 1234567,
  "secret": "Use code SECRET2026 — https://notion.so/promo?aff=...",
  "activated_at": "2026-05-20T14:30:00Z",
  "signup_url": "https://www.joinsecret.com/users/sign_up?utm_source=agent_api&utm_medium=agent&utm_campaign=your-agent-slug",
  "signup_incentive": "Create a free Secret account to unlock 50+ premium deals."
}
```

**Premium / eligibility-gated / unique-code deals — deeplink returned:**
```json
{
  "deal_slug": "premium-aws-credits",
  "product_slug": "aws",
  "requires_redirect": true,
  "redirect_url": "https://www.joinsecret.com/aws?utm_source=agent_api&utm_medium=agent&utm_campaign=your-agent-slug",
  "reason": "premium_signup_required"
}
```

`reason` is one of: `premium_signup_required`, `eligibility_questions_required`, `unique_code_required`.

### List categories
`GET /api/public/v1/categories`

Returns the taxonomy of categories used to organize our deals.

## Funnel preservation contract

When you serve a `secret` directly to your user, **you must also surface the `signup_incentive` text and the `signup_url` link**. This is how Secret recovers part of the user funnel it gives up by serving you directly. Agents that don't surface this contract may be rate-limited or revoked.

## Rate limits

Per IP:
- `200 requests/minute` on read endpoints
- `30 requests/minute` on activations

Exceeded → HTTP 429 with `Retry-After` header.

## Internationalization

All payloads are returned in English regardless of the agent's location. If your user speaks another language, translate on your side — the high-value payload (code, affiliate URL) is language-agnostic.

## Country availability

Each deal payload includes `excluded_country_codes` — countries where the deal is not available. You are responsible for filtering based on your user's location.

## Identifying yourself

Pick a stable, lowercase, dash-separated slug for your `X-Agent-Id` and use it consistently. We track activation volume per agent and may reach out if you grow into a significant integration.

## Questions or partnership

Email: hello@joinsecret.com