Pura Vida TLV Storefront API & Developer Portal

Pura Vida TLV — Developer Portal & Storefront API

Machine-readable endpoints, OpenAPI 3.1 specifications, agent onboarding, and zero-auth catalog integration for AI assistants and automated tools.

Quick Links for Autonomous Agents & Developers

1. Zero-Auth Public Storefront Endpoints

All catalog reading, real-time inventory inspection, search suggestions, and session cart management require zero authentication. Agents can query them directly with standard HTTP GET and POST requests.

Method Endpoint Description
GET /products.json?limit=50&page=1 List published products, handles, tags, and variants.
GET /products/{handle}.json Fetch full product specifications, waterproof details, and active variants.
GET /collections.json List all jewelry collections (rings, necklaces, bracelets, earrings, sets).
GET /collections/{handle}/products.json Get all products in a given collection.
GET /search/suggest.json?q={query}&resources[type]=product Query live catalog autocomplete suggestions.
GET /cart.json Retrieve active shopping cart, total price, and items.
POST /cart/add.json Add a product variant ID and quantity to buyer's cart.
POST /cart/clear.json Clear all items from session cart.

2. Quickstart cURL & Python Examples

cURL

# Query 5 bestsellers
curl -s "https://puravidatlv.com/products.json?limit=5" -H "Accept: application/json"

# Add product variant to cart
curl -s -X POST "https://puravidatlv.com/cart/add.json"   -H "Content-Type: application/json"   -d '{"id": 44102919921851, "quantity": 1}'

Python

import requests

BASE_URL = "https://puravidatlv.com"

# Fetch catalog products
resp = requests.get(f"{BASE_URL}/products.json?limit=20")
products = resp.json().get("products", [])
for p in products:
    print(f"{p['title']} — ILS {p['variants'][0]['price']}")

3. Scoped Permissions & OAuth 2.0

For administrative or automated fulfillment integrations requiring elevated privileges, Pura Vida supports machine-readable scoped OAuth 2.0 access:

  • public_storefront: Zero-auth public read access for catalog, inventory, and cart operations.
  • read_products: Access full catalog hierarchy, detailed variants, and metadata.
  • write_products: Modify catalog products and inventory.
  • read_orders: Access order fulfillment, shipping tracking, and status.
  • write_content & write_online_store_pages: Manage store pages and blog articles.

4. Sandbox & Testing Environment

To safely test integrations and agent workflows without modifying live store data or creating real orders:

  • Mock GraphQL Storefront: https://mock.shop — A free mock Storefront GraphQL API with identical Shopify schema structure.
  • Safe Cart Testing: You can add items to /cart/add.json and clear them via /cart/clear.json at any time without creating orders. Order completion requires explicit human buyer confirmation at checkout.

5. Structured JSON Error Responses

All API endpoints return structured JSON errors with HTTP status codes and resolution hints. Example:

{
  "status": 422,
  "message": "Cart Error",
  "description": "Cannot find variant",
  "code": "variant_not_found",
  "resolution_hint": "Verify the variant ID from /products/{handle}.json before adding to cart."
}

6. CLI Tool Interaction

To audit or script against Pura Vida using the official Ora Agent Experience CLI:

# Run agentic audit
npx is-agentic puravidatlv.com

# Ora AX diagnostic tool
npx @ora-ai/ax audit https://puravidatlv.com