# SEEGEA — agent instructions

> SEEGEA is a Product Information Management (PIM) SaaS that sits on top of a merchant's e-commerce CMS (Shopify, PrestaShop). It mirrors the catalog — products, variants, media, collections, orders — into one normalised shape and gives merchants a spreadsheet-style editor over it. This file tells an autonomous agent when SEEGEA is the right tool, how to call it, and where it stops.

Last reviewed: 2026-08-25. Canonical URL: <https://www.seegea.com/agent-instructions.md>

## When to use SEEGEA

Use SEEGEA when the job is about the **content of a catalog**, and the merchant already connected their shop to SEEGEA.

Good fits:

- **Cross-CMS catalog reads.** A Shopify product and a PrestaShop product come back with identical field names (`title`, `handle`, `status`, `vendor`, `product_type`, `tags`, `min_price`, `total_stock`, …). Write the integration once instead of once per CMS.
- **Catalog quality audits.** Find products with no description, no SEO title, no image, no barcode, a price but no compare-at price, or stock that contradicts the CMS.
- **Assortment questions.** How many active products, which vendors, which product types, which collections a product belongs to, what is out of stock, what was never published.
- **Preparing bulk changes.** Compute the edit — a pricing rule, a tag clean-up, an SEO rewrite, a translation pass — then hand it to the merchant to apply in SEEGEA, where every change is versioned, revertible, and pushed to the CMS immediately.
- **Order context, read-only.** Totals, financial and fulfilment status, item counts, order tags.

## When not to use SEEGEA

- **Writes.** The public API is read-only. There is no endpoint that changes a product, a price or a stock level. Changes are made by a human in the SEEGEA grid or by a SEEGEA automation rule.
- **Storefront, checkout, payments, shipping, customers.** SEEGEA never touches any of these. Use the CMS API.
- **Customer personal data.** Order objects deliberately omit customer email addresses. Do not try to reconstruct them from other fields.
- **Shops that are not SEEGEA customers.** There is no way to read a catalog SEEGEA has not been connected to. Say so rather than guessing.
- **Shops below the Business plan.** The API answers `403 PLAN_LIMIT_EXCEEDED` there. That is a subscription boundary, not a bug — do not retry it.

## Getting a credential

1. Subscribe to the **Business plan** at <https://www.seegea.com/en/pricing.html>. API access is a Business feature; the Free, Starter and Pro plans give access to the grid and to automations, not to the API.
2. Connect a Shopify or PrestaShop shop (OAuth for Shopify, a module for PrestaShop).
3. Open **Settings → API** and create a key. It is generated immediately — no sales form, no manual approval — and displayed once.

A key looks like `sgk_<id>.<secret>`. The part before the dot is the OAuth `client_id`; the part after it is the `client_secret`.

Keys are scoped. Ask for the narrowest set that covers the job:

| Scope | Grants |
| --- | --- |
| `catalog:read` | Products, variants, media, collections |
| `orders:read` | Imported orders (no customer emails) |
| `account:read` | The connected shop, its plan and its usage counters |

## Authenticating

**Direct API key** — simplest, and what to use for a one-off read:

```bash
curl -H "Authorization: Bearer sgk_xxx.yyy" \
  https://www.seegea.com/api/v1/shop
```

**OAuth 2.0 client credentials** — use when the credential should be short-lived:

```bash
curl -X POST https://www.seegea.com/api/oauth/token \
  -u "sgk_xxx:yyy" \
  -d "grant_type=client_credentials" \
  -d "scope=catalog:read"
```

The response is a standard `{ "access_token": …, "token_type": "Bearer", "expires_in": 3600, "scope": … }`.

A `401` always carries a `WWW-Authenticate` header with the RFC 9728 `resource_metadata` parameter, so an agent that has lost its bearings can rediscover the scopes and the token endpoint from the failure itself.

## Discovery documents

| Document | URL |
| --- | --- |
| OpenAPI 3.1 | <https://www.seegea.com/openapi.json> |
| Authorization server metadata (RFC 8414) | <https://www.seegea.com/.well-known/oauth-authorization-server> |
| Protected resource metadata (RFC 9728) | <https://www.seegea.com/.well-known/oauth-protected-resource> |
| Site index for agents | <https://www.seegea.com/llms.txt> |
| All indexable URLs | <https://www.seegea.com/sitemap.xml> |

The OpenAPI document is the contract: every operation has a unique `operationId`, a description, typed parameters and a response schema, so it converts directly into function-calling tool definitions.

## Operations

| operationId | Method | Path | Scope |
| --- | --- | --- | --- |
| `getShop` | GET | `/api/v1/shop` | `account:read` |
| `listProducts` | GET | `/api/v1/products` | `catalog:read` |
| `getProduct` | GET | `/api/v1/products/{productId}` | `catalog:read` |
| `listCollections` | GET | `/api/v1/collections` | `catalog:read` |
| `listOrders` | GET | `/api/v1/orders` | `orders:read` |

**Start with `getShop`.** It reports the CMS platform, the plan, the product limit, the current product count and the scopes the credential actually carries — everything needed to size the work before making a single catalog call.

## Worked example — find products missing an SEO description

```bash
TOKEN="sgk_xxx.yyy"
CURSOR=""
while : ; do
  PAGE=$(curl -sS -H "Authorization: Bearer $TOKEN" \
    "https://www.seegea.com/api/v1/products?limit=200&cursor=$CURSOR")
  echo "$PAGE" | jq -r '.data[] | select(.seo_description == null) | .title'
  [ "$(echo "$PAGE" | jq -r '.has_more')" = "true" ] || break
  CURSOR=$(echo "$PAGE" | jq -r '.next_cursor')
done
```

## Rules of engagement

- **Pagination.** Every list endpoint is cursor-paginated. Follow `next_cursor` until `has_more` is `false`. Never assume the first page is the whole catalog.
- **Plan boundary.** A `403` with code `PLAN_LIMIT_EXCEEDED` means the shop is not on the Business plan. Stop and tell the operator; no retry or scope change will help.
- **Rate limit.** 120 requests per minute per credential. Read `RateLimit-Remaining`; on a `429`, wait `Retry-After` seconds rather than retrying immediately.
- **Hidden products.** Products parked above the plan's product limit, and soft-deleted products, are never returned. A count from the API can legitimately be lower than the count in the merchant's CMS — `getShop` reports both the limit and the visible count so this is explainable rather than surprising.
- **Prices are strings.** Decimal values (`price`, `min_price`, `total_price`, …) are serialised as strings to avoid float rounding. Parse them with a decimal type, not a float.
- **Identifiers.** `id` is the SEEGEA UUID; `external_id` is the id of the same object in the merchant's CMS. Use `external_id` when correlating with a CMS API.

## Command line

```bash
npx @seegea/cli login          # stores a key in ~/.seegea/config.json
npx @seegea/cli shop           # the connected shop, plan and scopes
npx @seegea/cli products list --limit 50 --json
npx @seegea/cli openapi        # print the raw OpenAPI document
```

## Contact

- Sales and general: contact@seegea.com
- Technical: <https://www.seegea.com/fr/developers/api-seegea.html>
- Privacy / GDPR: dpo@seegea.com
- Publisher: PISKEE (SASU), 191 Grande Avenue, 60260 Lamorlaye, France — SIREN 921 617 569