Delphra
Developer Quickstart

API Reference & Guides

Learn how to authenticate requests, invoke the product enrichment endpoint, and parse structured category intelligence.

Authentication

All requests must include your provisioned key in the X-API-Key request header. The key is validated in constant time and cached briefly for rapid verification at the edge.

HTTP Header 
X-API-Key: dlp_live_abcdef1234567890abcdef1234567890

Never expose secret keys in client-side code or public repositories. Requests missing the header or presenting invalid keys are rejected immediately with 401 Unauthorized (accompanied by a WWW-Authenticate: ApiKey response header).

Endpoints Reference

The enrichment service exposes a primary synchronous endpoint via HTTP POST:

POST /api/v1/enrich_product 
POST https://api.delphra.com/api/v1/enrich_product
Host: api.delphra.com
Content-Type: application/json
X-API-Key: dlp_live_YOUR_KEY_HERE

The endpoint accepts product metadata in the request body, coordinates Gemini multimodal reasoning across textual and image inputs, and returns a verified classification.

Request Schema

The endpoint consumes a payload conforming to the ProductSchema specification. Fields marked required must be present in every request:

Field Type Required Description
id UUID Yes Unique record UUID identifier (e.g., "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11").
source_id string Yes Retailer source identifier or SKU (max 255 chars).
retailer string Yes Merchant or retailer identifier (max 100 chars).
collected_at datetime Yes ISO 8601 timestamp when product record was collected.
updated_at datetime Yes ISO 8601 timestamp when record was last updated.
ingested_at datetime Yes ISO 8601 timestamp when product entered processing.
product_name string No Product title or display name (max 255 chars).
brand string No Brand or manufacturer name (max 100 chars).
product_url string (URL) No Canonical web URL for the product page.
image_url string (URL) No Primary high-resolution product image for visual reasoning.
image_urls string[] (URLs) No List of additional product gallery images.
price decimal No Standard retail price (max 10 digits, 2 decimal places).
sales_price decimal No Promotional or discounted sales price.
currency string No Three-letter uppercase currency code (e.g. "USD").
in_stock boolean No Inventory availability indicator.
description string No Raw textual product description.
materials string No Fabric composition and materials specification.
available_sizes object[] No Structured sizing availability matrix.
rating float No Customer review score aggregate.
reviews_count integer No Total count of customer reviews.

cURL Quickstart

Make a direct HTTPS POST request to https://api.delphra.com/api/v1/enrich_product with a JSON payload satisfying the product input schema.

cURL 
curl -X POST "https://api.delphra.com/api/v1/enrich_product" \
  -H "X-API-Key: dlp_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "source_id": "item_10293",
    "retailer": "example-retailer",
    "product_name": "Linen Wrap Midi Dress",
    "brand": "Delphra Studio",
    "product_url": "https://example.com/product/10293",
    "image_url": "https://example.com/images/10293.jpg",
    "price": "180.00",
    "currency": "USD",
    "collected_at": "2026-09-20T20:00:00Z",
    "updated_at": "2026-09-20T20:00:00Z",
    "ingested_at": "2026-09-20T20:00:00Z"
  }'

Python Example

Integrate enrichment directly into your Python data processing jobs using httpx or requests.

Python 3.10+ (httpx) 
import httpx

API_ENDPOINT = "https://api.delphra.com/api/v1/enrich_product"
API_KEY = "dlp_live_YOUR_KEY_HERE"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
}

payload = {
    "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "source_id": "sku_8741",
    "retailer": "example-retailer",
    "product_name": "Cashmere Oversized Turtleneck",
    "image_url": "https://images.example.com/sku_8741.jpg",
    "currency": "USD",
    "price": "340.00",
    "collected_at": "2026-09-20T20:00:00Z",
    "updated_at": "2026-09-20T20:00:00Z",
    "ingested_at": "2026-09-20T20:00:00Z",
}

with httpx.Client(timeout=30.0) as client:
    response = client.post(API_ENDPOINT, json=payload, headers=headers)

    if response.status_code == 200:
        result = response.json()
        print(f"Product Selected: {result['include']}")
        print(f"Category: {result.get('product_type')}")
        print(f"Reasoning: {result['reason']}")
    elif response.status_code == 204:
        print("Pipeline ran but produced no conclusive output (unbilled).")
    elif response.status_code == 401:
        print("Unauthorized: Missing or invalid API key.")
    elif response.status_code == 402:
        print("Payment Required: Account suspended for non-payment.")
    elif response.status_code == 429:
        print(f"Too Many Requests: {response.text}")
    else:
        print(f"Request error {response.status_code}: {response.text}")

Response Schema

The endpoint guarantees structured JSON matching the validated ProductAnalysisResult model:

Field Type Required Description
include boolean Yes Whether or not the product was selected based on criteria analysis.
reason string Yes Explanation of why the product was selected or excluded.
keywords string[] No Keywords matching the inclusion criteria keywords.
life_stages string[] No Lifestage annotations: "First Trimester", "Second Trimester", "Third Trimester", "Postpartum".
occasions string[] No Occasion annotations: "Wardrobe Staples", "Party", "Wedding Guest", "Workwear", "Vacation".
category_id string No Mapped standardized taxonomy category identifier (e.g. Shopify category ID).
product_type string No Product type classification: "Accessories", "Shoes", "Dresses", "Knitwear", "Outerwear", "Skirts", "Tops", "Bottoms".
tags string[] No Specific functional tags: "Pump friendly", "Nursing friendly", "C-Section friendly".
ai_review string No Synthesized summary of customer reviews and garment performance.

Error Codes

The API returns standard HTTP status codes. Client-facing error messages are sanitized to safeguard internal infrastructure:

Status Meaning Cause & Remediation
200 OK Success Product enriched successfully. Response contains a validated ProductAnalysisResult object. Billed.
204 No Content No Result Produced The agent completed inference but generated no conclusive classification. Unbilled.
401 Unauthorized Authentication Failure Missing, malformed, revoked, or invalid X-API-Key. Returns WWW-Authenticate: ApiKey.
402 Payment Required Account Past Due Account is suspended for non-payment. Customer must update payment details in Stripe billing.
403 Forbidden Scope Insufficient Key does not possess the requisite operational scope for this resource.
429 Too Many Requests Quota or Rate Limit Exceeded Triggered by Cloud Armor per-key rate limiting, monthly request/token cap exhaustion, or upstream Gemini quota exhaustion.
500 Server Error Internal Exception Internal processing error. The server returns a sanitized notice; safe to retry with exponential backoff. Unbilled.

Rate Limits & Quotas

Delphra enforces two layers of protective throttling:

  • Cloud Armor Edge Guard: Each API key receives an independent token bucket throttled on requests per minute. Burst traffic exceeding the threshold receives immediate 429 responses without incurring inference costs.
  • Monthly Account Cap: Every billing plan enforces a total monthly allowance. When reached, subsequent requests return 429 (Monthly quota exhausted) until the calendar month rolls over or an overage plan is enabled.