API Reference

Build on top of cross-domain taste intelligence. Our REST API lets you query taste profiles, get recommendations, and generate shareable fingerprints.

Base URL: api.tastegraph.ioVersion: v1

Quick Start

import tastegraph

client = tastegraph.Client("tg_your_api_key")

# Get a user's taste profile
profile = client.profiles.get("usr_abc123")
print(profile.domains["music"].top_traits)

# Get cross-domain recommendations
recs = client.recommend(
    user_id="usr_abc123",
    target_domain="food",
    source_domains=["music", "fashion"],
    limit=5
)

for rec in recs:
    print(f"{rec.item} (score: {rec.match_score})")

Authentication

All API requests require a Bearer token. Get your API key from the dashboard.

Authorization: Bearer tg_your_api_key

Important: Keep your API key secret. Never expose it in client-side code. Use environment variables and server-side requests.

Rate Limits

Plan	Rate Limit	Burst
Free	100 req/hour	10 req/sec
Developer	10,000 req/hour	100 req/sec
Enterprise	Unlimited	Custom

Endpoints

GET/v1/profile/{user_id}

Get Taste Profile

Retrieve the full cross-domain taste profile for a user.

Parameters

user_idstringrequired

The unique user identifier

domainsstring[]

Filter to specific domains (music, food, fashion, architecture, film)

Response

{
  "user_id": "usr_abc123",
  "created_at": "2026-01-15T09:30:00Z",
  "domains": {
    "music": {
      "top_traits": ["experimental", "rhythmic", "melancholic"],
      "confidence": 0.92
    },
    "food": {
      "top_traits": ["umami-forward", "fermented", "spicy"],
      "confidence": 0.87
    },
    "fashion": {
      "top_traits": ["minimalist", "textured", "monochrome"],
      "confidence": 0.79
    }
  },
  "cross_domain_patterns": [
    {
      "pattern": "texture-seeking",
      "domains": ["music", "food", "fashion"],
      "strength": 0.91
    }
  ]
}

POST/v1/profile/{user_id}/analyze

Analyze Preferences

Submit preference data for analysis. Returns updated taste signals.

Parameters

user_idstringrequired

The unique user identifier

domainstringrequired

The taste domain

preferencesobject[]required

Array of preference items with scores

Response

{
  "status": "analyzed",
  "domain": "music",
  "new_traits": ["experimental", "layered"],
  "confidence_delta": +0.05,
  "cross_domain_updates": 2
}

GET/v1/recommend/{user_id}

Get Recommendations

Get cross-domain recommendations based on taste profile.

Parameters

user_idstringrequired

The unique user identifier

target_domainstringrequired

Domain to get recommendations for

source_domainsstring[]

Domains to base recommendations on

limitnumber

Max results (default: 10)

Response

{
  "recommendations": [
    {
      "item": "Noma-style fermented garlic",
      "domain": "food",
      "based_on": ["music:experimental", "fashion:textured"],
      "match_score": 0.94,
      "reasoning": "Your love for layered, experimental music and textured fashion maps to complex umami profiles"
    }
  ],
  "total": 10
}

GET/v1/fingerprint/{user_id}

Get Taste Fingerprint

Generate a shareable taste fingerprint card with visualization data.

Parameters

user_idstringrequired

The unique user identifier

formatstring

"json" or "svg" (default: json)

Response

{
  "fingerprint_id": "fp_xyz789",
  "share_url": "https://taste.graph/fp/xyz789",
  "visualization": {
    "nodes": [...],
    "edges": [...],
    "color_palette": ["#FF6B6B", "#7C3AED"]
  },
  "summary": "Texture-seeking experimentalist with a bias toward the melancholic and umami-forward"
}

Ready to build with taste intelligence?

Get Your API Key