feedico-io Global catalogue API

openapi: 3.2.0
info:
  title: Feedico customer data Global catalogue API
  version: 1.4.0
  description: 'Feedico exposes complementary **POST-only** list APIs (JSON body, may be `{}`). **`GET`** is not supported (`405`).


    ### Auth (tenant identity)

    **`Authorization: Bearer fdco_...`** from dashboard **Account**.

    The API **never** accepts `userId` / account id in the JSON body — the tenant is resolved only from the token → `app_users`.


    ### Your account (`/api/v1/me/*`)

    Merchant programmes, coupons, and **products** from **your** connected affiliate networks.

    Coupon/product rows may include **`offerUrl`** (your synced affiliate links). Products include **`images[]`**.


    ### Global catalogue (`/api/v1/catalog/*`)

    Aggregated index across **all Feedico tenants** — useful for discovery, SEO tooling, and coupon-site research.

    - **`POST /api/v1/catalog/networks`** — firms deduplicated by **display name**.

    - **`POST /api/v1/catalog/coupons`** — promo codes with a non-empty **`code`**, deduplicated by **brand + code**.

    - **`POST /api/v1/catalog/products`** — products (newest first; no `offerUrl`).

    - Rows from Feedico''s managed catalogue include a ready tracked link, **`goUrl`** (null for stores we don''t manage). Use it as the link on your "Get deal" / "Shop" buttons. Want to earn the commission yourself? Join the free Partner Program (you keep 65%): its API returns links with your own partner ID.

    - Includes **CJ, Impact, Admitad, …** unified rows **and** **Awin** programme + voucher snapshots (coupons/firms).


    ### Auth & quota

    Each successful **`/api/v1/me/*`** or **`/api/v1/catalog/*`** response counts **one** request against your plan’s monthly API cap (UTC month). Over limit → **`429`** **`monthly_api_limit`**.


    ### Pagination & filters

    - **`recordCount`** — total matching filters. On `/api/v1/catalog/products`, filtered queries return an exact count up to 10,000 (`recordCountApproximate: false`), above 10,000, or when counting takes too long, it is a lower bound with `recordCountApproximate: true`. Unfiltered browsing returns the catalogue size estimate.

    - **`page`** / **`pageSize`** — firms/coupons max **200**; **products max 500** (default **50**). Prefer **`cursor`** / **`nextCursor`** for large product feeds (keyset pagination; avoids deep OFFSET).

    - **`provider`** — e.g. `cj_affiliate`; omit for all sources.

    - **`firmName`**, product extras: **`q`**, **`brand`**, **`sku`**, **`currency`**, **`minPrice`**, **`maxPrice`**.

    - **`includeInactive`** — default `false`.'
servers:
- url: https://api.feedico.io
  description: Production
- url: http://127.0.0.1:3010
  description: Local Next (`next start` same port as systemd feedico-web)
tags:
- name: Global catalogue
  description: Cross-tenant aggregated firms, coupons, and products (`POST /api/v1/catalog/*`). No `offerUrl`.
paths:
  /api/v1/catalog/products:
    post:
      tags:
      - Global catalogue
      summary: Global catalogue products — paginated POST
      operationId: catalogProducts
      security:
      - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductListRequest'
            examples:
              brandedRelevance:
                summary: Branded products, marketplaces excluded, best match first
                value:
                  q: wireless meat thermometer
                  excludeFirms:
                  - DHgate
                  - Temu
                  - TikTok Shop
                  brandedOnly: true
                  sort: relevance
                  pageSize: 20
              partNumber:
                summary: Look up a part number / SKU
                value:
                  sku: WPW10503278
                  pageSize: 20
      responses:
        '200':
          description: Deduplicated catalogue products (no offerUrl)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogProductsResponse'
        '401':
          description: Missing or invalid bearer
        '429':
          description: Monthly API quota exceeded
components:
  schemas:
    CatalogProductsResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    ProductListRequest:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true