JENNi Service API

openapi: 3.2.0
info:
  contact:
    email: partners@jennipro.com
    name: JENNi partner integrations
  description: 'One API, read by four kinds of partner. **Get started** (left) is the same for everyone:

    sign up, get a key, make five calls. Then pick who you are: each card names the guide to

    read first and the API sections you will actually call, in that order. The sidebar is

    grouped the same way; everything cross-cutting (errors, paging, limits, versioning) sits

    under **Reference** at the end.


    POS systems


    You run the point of sale, inventory or product-data system for retailers, and you push their catalog and live stock into JENNi.


    What you do: register each store, open a run, push products and stock levels (or a full snapshot), close the run, read back what landed.


    Read, then call: POS: catalog & inventory → Stores · Runs · Catalog · Inventory


    First call: POST /provider/v1/stores


    Live in production.


    Brands


    You own the product content — titles, images, descriptions, GTINs — for products that retailers stock, and you want JENNi''s listings to carry your version.


    What you do: send product records through the same ingestion lane a POS uses, then make sure each one clears the readiness bar, because a record that lands but is not ready is never sold.


    Read, then call: Brands → Product readiness → Catalog (listed under POS systems)


    First call: GET /provider/v1/products


    Same lane as POS. Brand-to-retailer matching is handled by JENNi, not by an API call.


    Marketplaces & channels


    You are a demand channel — a marketplace, delivery app or storefront — that lists JENNi merchants'' stock and sends orders back.


    What you do: read one store''s shelf at a time, poll or receive changes, and agree an order path with JENNi (orders in are a JENNi-built adapter, not a public endpoint).


    Read, then call: Marketplace & channel → Channel · Events · Webhooks


    First call: GET /channel/v1/stores


    The read contract is settled and documented; it is enabled per channel — the guide says what is callable today.


    Fulfillment & delivery


    You pick, pack, ship or hand over orders for JENNi merchants.


    What you do: today, plan. The fulfillment service has no partner-callable route; the guide documents what is built so you can scope against it.


    Read: Fulfillment & delivery


    First call: none yet — talk to your JENNi contact.


    Planning only today; talk to your JENNi contact before building.


    ## Before your first call


    - **Get a credential:** *Sign in / Sign up* (top right) → verify your email → *Request a

    key*. JENNi approves it and you claim the secret once — Quickstart walks

    through it.

    - **Base URLs:** `https://prod.jennipro.net` is production; `https://dev.jennipro.app` is the

    sandbox, with its own credentials issued on request.

    - **Credential:** `X-Jenni-Api-Key: .` on every request — see

    Authentication and Scopes. Your tenant and provider come

    from the key; no tenant id ever travels in a path or body.

    - **Errors** are RFC-7807 `application/problem+json`; branch on `type`, quote

    `X-Request-Id` to support — see Errors.

    - **Writes** carry `Idempotency-Key`; lists page with `cursor` + `limit` — see

    Idempotency and Pagination.


    Where a capability is not yet available to partners, the page says so in place.'
  title: JENNi Catalog & Inventory Ingestion Service API
  version: '2026-09-20'
servers:
- description: Production
  url: https://prod.jennipro.net
- description: Development / integration sandbox
  url: https://dev.jennipro.app
security:
- PartnerApiKey: []
tags:
- description: Liveness and readiness probes. Internal — not part of the partner contract.
  name: Service
paths:
  /health:
    get:
      description: Liveness probe. Reports the service's configured mode and does NOT probe dependencies, so it stays green while a downstream is degraded. Internal — not part of the partner contract.
      operationId: getHealth
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthView'
          description: The service is up.
          headers:
            X-Request-Id:
              description: Correlation id for this request — echoed from X-Request-Id when you sent one, otherwise generated.
              schema:
                type: string
      security: []
      summary: Liveness probe
      tags:
      - Service
      x-internal: true
  /healthz:
    get:
      description: Liveness probe. Reports the service's configured mode and does NOT probe dependencies, so it stays green while a downstream is degraded. Internal — not part of the partner contract.
      operationId: getHealthz
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthView'
          description: The service is up.
          headers:
            X-Request-Id:
              description: Correlation id for this request — echoed from X-Request-Id when you sent one, otherwise generated.
              schema:
                type: string
      security: []
      summary: Liveness probe (alias)
      tags:
      - Service
      x-internal: true
  /readyz:
    get:
      description: 'Readiness probe. Pings the run-registry database when running against Postgres and fails the pod out of the load-balancer rotation if that ping fails. Internal — not part of the partner contract.


        Note this is the one endpoint whose error body is NOT RFC-7807: it answers the kubelet, which ignores the body entirely.'
      operationId: getReadiness
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadyView'
          description: Ready to serve traffic.
          headers:
            X-Request-Id:
              description: Correlation id for this request — echoed from X-Request-Id when you sent one, otherwise generated.
              schema:
                type: string
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadyView'
          description: Not ready — a required dependency is unreachable. Body is deliberately NOT problem+json; this endpoint answers the kubelet, not a partner.
          headers:
            X-Request-Id:
              description: Correlation id for this request — echoed from X-Request-Id when you sent one, otherwise generated.
              schema:
                type: string
      security: []
      summary: Readiness probe
      tags:
      - Service
      x-internal: true
components:
  schemas:
    HealthView:
      properties:
        authMode:
          type: string
        dataSource:
          type: string
        partnerAuth:
          type: string
        service:
          type: string
        status:
          type: string
      required:
      - status
      - service
      - dataSource
      - authMode
      - partnerAuth
      title: HealthView
      type: object
    ReadyView:
      properties:
        reason:
          type: string
        status:
          type: string
      required:
      - status
      title: ReadyView
      type: object
  securitySchemes:
    PartnerApiKey:
      description: 'Your partner API key, sent as `{keyId}.{secret}` — the key id, one dot, then the secret. The value is split on the FIRST dot only, so a secret that itself contains dots is handled correctly; do not trim or re-encode it. The key determines your tenant and your provider: there is no tenant parameter anywhere in this API. Keys are revoked immediately when rotated, so treat a 401 as final rather than retrying it.'
      in: header
      name: X-Jenni-Api-Key
      type: apiKey
    PartnerBearer:
      bearerFormat: JWT
      description: 'The partner portal session token, sent as `Authorization: Bearer <token>`. It is issued by the portal login (identity-service `/v1/partner/auth/login`) and expires after an hour; refresh it with the refresh token rather than logging in again. It authenticates the `/provider/v1/portal/*` routes ONLY — an API key is refused there with `403 missing-scope`, and this token is refused on every other route with `401 invalid-auth`. The two credentials never substitute for each other.'
      scheme: bearer
      type: http
x-jenni-field-groups:
  core:
    cost: 2
    fields:
    - jenni_product_id
    - jenni_product_store_id
    - jenni_store_id
    - store_id
    - in_stock
    - modified_at
  groups:
  - cost: 1
    fields:
    - gtin
    - upc
    name: identifiers
  - cost: 3
    fields:
    - title
    - brand
    - color
    - size
    - product_link
    name: content
  - cost: 2
    fields:
    - price
    - sale_price
    name: pricing
  - cost: 1
    fields:
    - inventory
    name: availability
  - cost: 1
    fields:
    - sku
    - source_run_id
    name: attribution
x-tagGroups:
- name: Get started
  tags:
  - Quickstart
  - Authentication
  - Scopes
  - Platform basics
  - Sandbox
- name: POS systems
  tags:
  - POS integration brief
  - 'POS: catalog & inventory'
  - Retailers & claim links
  - Retailers
  - Stores
  - Runs
  - Catalog
  - Inventory
- name: Brands
  tags:
  - Brands
  - Product readiness
- name: Marketplaces & channels
  tags:
  - Marketplace & channel
  - Channel
  - Events
  - Webhooks
  - Webhooks guide
- name: Fulfillment & delivery
  tags:
  - Fulfillment & delivery
- name: Reference
  tags:
  - Errors
  - Idempotency
  - Pagination
  - Rate limits
  - Versioning
  - Support
  - Changelog
  - Account
  - Portal
  - Brand portal
x-jenni-portal:
  injected_by: jenni-developer-portal/inject_guides.py
  sources:
  - pos-integration-brief.md
  - pos-catalog-inventory.md
  - brands.md
  - product-readiness.md
  - marketplace-channel.md
  - fulfillment-delivery.md
  - platform-basics.md
  - sandbox.md
  - retailers-and-claims.md
  - quickstart.md
  - authentication.md
  - scopes.md
  - errors.md
  - idempotency.md
  - pagination.md
  - rate-limits.md
  - versioning.md
  - webhooks.md
  - support.md
  - CHANGELOG.md
  - landing.md
  source_headings:
  - POS integration brief
  - 'Guide A — POS systems: catalog and inventory ingestion'
  - 'Guide D — Brands: product content through the ingestion lane'
  - Product readiness — what makes a product sellable
  - Marketplace and channel reads
  - Guide C — Fulfillment and delivery providers
  - Platform basics
  - Sandbox — what a self-serve key can do, what it cannot, and how to leave it
  - 'Guide E — Retailers: register a merchant and hand them a claim link'
  - Quickstart
  - Authentication
  - Scopes
  - Errors
  - Idempotency
  - Pagination
  - Rate limits
  - Versioning
  - Webhooks guide
  - Support
  - Changelog
  - JENNi Partner API
  landing: landing.md