# Pionery — Comprehensive Machine-Readable API & Data Schema Reference

> Full specification and integration guide for autonomous AI procurement agents, LLMs, and enterprise B2B sourcing systems.

Base URL: https://pionery.com
API Base: https://pionery.com/api/public
OpenAPI 3.1 Spec: https://pionery.com/api/openapi.json
Documentation: https://pionery.com/de/api-doku
Sitemap: https://pionery.com/sitemap.xml
Specification: https://llmstxt.org

---

## 1. Core Platform Architecture

Pionery connects four principal B2B actors across Europe and global manufacturing hubs:
1. **Buyers / Einkäufer**: Issue tenders (RFQs), browse products, and negotiate in confidential deal rooms.
2. **Manufacturers / Hersteller**: Verified factories offering catalog products, OEM manufacturing, and private labeling.
3. **Freight Forwarders / Spediteure**: Logistics providers handling international cross-border cargo (truck, ocean, air, rail).
4. **Sourcing Agents / Handelsvertreter**: On-the-ground agents providing quality inspections, factory audits, and translation.

---

## 2. API Response Wrapper Format

All public JSON endpoints return data enclosed in a consistent envelope:

```json
{
  "schema_version": "1.0",
  "license": "Open Access for AI and B2B Sourcing Agents — Pionery (https://pionery.com)",
  "source": "https://pionery.com",
  "timestamp": "2026-09-09T10:00:00.000Z",
  "meta": {
    "total": 120,
    "limit": 50,
    "offset": 0,
    "returned": 50,
    "next_offset": 50,
    "has_more": true
  },
  "items": [ /* Array of entity records */ ]
}
```

For single-entity endpoints (`/api/public/produkte/{id}`, `/api/public/hersteller/{id}`), the object is returned in `"data"`.

---

## 3. Detailed Data Schemas

### 3.1 Product Schema (`/api/public/produkte`)
| Field | Type | Description |
|---|---|---|
| `id` | string (UUID) | Unique product identifier |
| `name` | string | Product name / title |
| `slug` | string \| null | SEO-friendly URL slug |
| `beschreibung` | string \| null | Product description & technical properties |
| `bild_url` | string \| null | Primary product photo URL |
| `kategorie` | string \| null | Standardized category |
| `preis_netto` | number \| null | Base unit price (excl. VAT) |
| `waehrung` | string | Currency code (default: `EUR`) |
| `preis_auf_anfrage` | boolean | True if price is negotiable / on request |
| `staffelpreise` | array | Tiered prices: `[{ "min_menge": 100, "preis": 4.50 }, ...]` |
| `einheit` | string | Unit of measurement (e.g. `Stück`, `kg`, `m`, `Set`) |
| `mindestbestellmenge` | number \| null | Minimum Order Quantity (MOQ) |
| `lieferzeit_tage` | number \| null | Minimum production / lead time in days |
| `lead_time_tage_max` | number \| null | Maximum production lead time in days |
| `ursprungsland` | string \| null | Country of production / origin |
| `zolltarifnummer` | string \| null | HS Customs Tariff Code (e.g. `8466.93.00`) |
| `muster_verfuegbar` | boolean | Whether product samples can be ordered |
| `muster_preis` | number \| null | Net sample price if applicable |
| `anpassbar_oem` | boolean | Supports OEM customization or private label |
| `verpackung_einheit` | string \| null | Master carton / packaging unit |
| `verpackung_gewicht_kg` | number \| null | Gross weight per packaging unit in kg |
| `verpackung_abmessungen_cm` | string \| null | Packaging dimensions (e.g. `40x30x25`) |
| `incoterms_angebot` | string[] | Supported Incoterms (e.g. `["FOB", "EXW", "DDP"]`) |
| `hersteller_artikelnummer` | string \| null | Manufacturer Part Number (MPN / SKU) |
| `spezifikationen` | object | Key-value specifications map |
| `zertifikate` | string[] | Product certifications (e.g. `["CE", "RoHS", "ISO 9001"]`) |
| `manufacturer` | object \| null | Summary: `{ id, name, country, city, profile_url }` |
| `url` | string | Canonical human-readable product URL |
| `inquiry_url` | string | URL to start an RFQ prefilled with this product |

### 3.2 Manufacturer Schema (`/api/public/hersteller`)
| Field | Type | Description |
|---|---|---|
| `id` | string (UUID) | Unique manufacturer ID |
| `name` | string | Company name or trade name |
| `country` | string \| null | Country of operation |
| `city` | string \| null | Production facility location |
| `avatar_url` | string \| null | Company logo URL |
| `verified` | boolean | Verification check passed by Pionery |
| `categories` | string[] | Offered product and industry categories |
| `certificates` | string[] | Quality and factory certifications |
| `capacity_per_month` | string \| null | Stated monthly production capacity |
| `min_order_value` | string \| null | Minimum order value (MOV) |
| `avg_lead_time_days` | string \| null | Typical manufacturing lead time in days |
| `description` | string \| null | Company overview and machinery description |
| `published_products_count` | number | Number of active published products |
| `profile_url` | string | Canonical human-readable profile link |

### 3.3 Freight Forwarder Schema (`/api/public/spediteure`)
| Field | Type | Description |
|---|---|---|
| `id` | string (UUID) | Unique forwarder ID |
| `name` | string | Company name |
| `country` | string \| null | Headquarter country |
| `verified` | boolean | Verified logistics partner |
| `transport_modes` | string[] | Modes (e.g. `["LKW", "Seefracht", "Luftfracht", "Schiene"]`) |
| `covered_routes` | string[] | Regular shipping lanes |
| `served_countries` | string[] | List of served destination countries |
| `fleet` | string[] | Fleet details |
| `specializations` | string[] | Heavy cargo, cold chain, dangerous goods, etc. |
| `certificates` | string[] | Logistics certifications (AEO, ISO 28000, etc.) |
| `description` | string \| null | Logistics capabilities & company bio |

### 3.4 Sourcing Agent Schema (`/api/public/agents`)
| Field | Type | Description |
|---|---|---|
| `id` | string (UUID) | Unique agent ID |
| `name` | string | Agent or agency name |
| `country` | string \| null | Operating country |
| `verified` | boolean | Verified sourcing agent |
| `languages` | string[] | Spoken business languages |
| `services` | string[] | Factory audits, sampling, quality control, price negotiation |
| `industries` | string[] | Specialized industries |
| `experience_countries` | string[] | Countries with active supplier network |
| `years_of_experience` | number \| null | Years in international trade |

### 3.5 Tender / RFQ Schema (`/api/public/ausschreibungen`)
| Field | Type | Description |
|---|---|---|
| `id` | string (UUID) | Unique tender identifier |
| `title` | string | Tender title |
| `category` | string \| null | Industry category |
| `description` | string \| null | Scope of work / technical requirements |
| `material` | string \| null | Requested material specification |
| `process` | string \| null | Manufacturing process (e.g. CNC turning, stamping) |
| `quantity` | number \| null | Required batch or total quantity |
| `unit` | string | Unit of measurement |
| `price_min` | number \| null | Target price minimum |
| `price_max` | number \| null | Target price maximum |
| `delivery_country` | string \| null | Destination delivery country |
| `delivery_city` | string \| null | Destination city / postal code |
| `deadline` | string (ISO) \| null | Proposal submission deadline |
| `incoterms` | string \| null | Requested Incoterms |
| `certificates` | string \| null | Required supplier certifications |
| `status` | string | Current tender status (`active`) |
| `url` | string | Canonical link to view tender and submit offer |

---

## 4. Complete Platform Categories

1. **Produktion & Industrie**:
   - Metall & Maschinenbau
   - Elektronik & Elektrotechnik
   - Automotive & Fahrzeugteile
   - Chemie & Kunststoff
   - Rohstoffe & Materialien
   - Werkzeuge & Betriebsmittel
   - Luft- & Raumfahrt
   - Schiffbau & Marine
   - Bergbau & Rohstoffgewinnung
   - Textilmaschinen & Equipment

2. **Konsumgüter**:
   - Textilien & Bekleidung
   - Schuhe & Leder
   - Sport & Outdoor
   - Spielzeug & Baby
   - Möbel & Inneneinrichtung
   - Haushaltsartikel
   - Schmuck & Uhren
   - Haustier & Tierbedarf
   - Musik & Instrumente
   - Büro & Schreibwaren

3. **Lebensmittel & Gesundheit**:
   - Lebensmittel & Getränke
   - Kosmetik & Körperpflege
   - Medizin & Pharma
   - Nahrungsergänzung
   - Reinigung & Hygiene
   - Sicherheit & Schutzausrüstung

4. **Druck & Verpackung**:
   - Druck & Werbemittel
   - DTF & Digitaldruck
   - Werbetechnik & Schilder
   - Verpackung & Etiketten
   - Papier & Kartonage

5. **Bau & Energie**:
   - Bau & Baustoffe
   - Solar & Energie
   - Beleuchtung & LED
   - Architektur & Design

6. **Technologie & Services**:
   - Software & IT
   - E-Commerce & Fulfillment
   - Events & Messen
   - Bildung & Training

7. **Landwirtschaft & Umwelt**:
   - Landwirtschaft & Gartenbau
   - Recycling & Nachhaltigkeit

---

## 5. Python Integration Example

```python
import requests

def search_pionery_products(category: str = None, country: str = None, max_moq: int = None):
    params = {
        "limit": 50,
        "kategorie": category,
        "land": country,
        "moq_max": max_moq
    }
    # Remove None values
    params = {k: v for k, v in params.items() if v is not None}
    
    url = "https://pionery.com/api/public/produkte"
    resp = requests.get(url, params=params, headers={"Accept": "application/json"})
    resp.raise_for_status()
    data = resp.json()
    
    print(f"Found {data['meta']['total']} matching products.")
    for item in data.get("items", []):
        mfg = item.get("manufacturer") or {}
        price = "On request" if item.get("preis_auf_anfrage") else f"{item.get('preis_netto')} {item.get('waehrung')}"
        print(f"- {item['name']} | MOQ: {item.get('mindestbestellmenge')} | Price: {price} | Supplier: {mfg.get('name')} ({mfg.get('country')})")

if __name__ == "__main__":
    search_pionery_products(category="Metall & Maschinenbau", max_moq=1000)
```