Code Examples & Recipes

← Return to Media Studio•DEVELOPER & EDGE API GATEWAY

Practical, production-ready code examples in cURL, TypeScript/JavaScript, and Python for the most common VISTARMAN API workflows.

Use Case 01

Lexical BM25 Search across Canon

Search through all 236+ peer-reviewed articles and receive scored results with summaries.

cURL (Terminal)

curl "https://api.vistarman.com/v1/search?q=consciousness&limit=3"

TypeScript / JavaScript (Native Fetch)

interface SearchResultItem {
  doc_id: string;
  title: string;
  slug: string;
  summary: string;
  score: number;
  url: string;
}

async function searchKnowledge(query: string): Promise<SearchResultItem[]> {
  const url = new URL("https://api.vistarman.com/v1/search");
  url.searchParams.set("q", query);
  url.searchParams.set("limit", "5");

  const response = await fetch(url.toString(), {
    headers: { "Accept": "application/json" },
  });

  if (!response.ok) {
    throw new Error(`Search failed with HTTP ${response.status}`);
  }

  const data = await response.json();
  return data.results || [];
}

Python (Requests)

import requests

def search_articles(query: str, limit: int = 5):
    endpoint = "https://api.vistarman.com/v1/search"
    params = {"q": query, "limit": limit}
    
    response = requests.get(endpoint, params=params, timeout=10)
    response.raise_for_status()
    
    data = response.json()
    return data.get("results", [])

# Example usage
results = search_articles("consciousness")
for r in results:
    print(f"[{r['score']:.2f}] {r['title']} -> {r['url']}")

Use Case 02

Retrieve Article Metadata & Graph Recommendations

Fetch single article metadata, canonical permalink, and pairwise related concept recommendations.

TypeScript / JavaScript

async function getArticleDetail(slug: string) {
  const res = await fetch(`https://api.vistarman.com/v1/articles/${slug}`);
  if (!res.ok) throw new Error(`Article not found: ${slug}`);
  
  const data = await res.json();
  console.log("Title:", data.title);
  console.log("Canonical:", data.canonical_url);
  console.log("Recommendations:", data.recommendations);
  return data;
}

Python

import requests

def get_article(slug: string):
    url = f"https://api.vistarman.com/v1/articles/{slug}"
    r = requests.get(url)
    r.raise_for_status()
    return r.json()

article = get_article("apps-architecture-map")
print("Article Title:", article["title"])
print("Recommendations Count:", len(article.get("recommendations", [])))

Use Case 03

Query Knowledge Graph Connections

Traverse the 1,541-edge ontological graph to discover semantically adjacent concepts.

cURL

curl "https://api.vistarman.com/v1/recommendations/doc:article:apps-architecture-map"

Python

import requests

def get_concept_recommendations(concept_id: str):
    url = f"https://api.vistarman.com/v1/recommendations/{concept_id}"
    res = requests.get(url)
    res.raise_for_status()
    return res.json().get("recommendations", [])

recs = get_concept_recommendations("doc:article:apps-architecture-map")
for rec in recs:
    print(f"Target: {rec['target_id']} (Weight: {rec['weight']:.2f})")