API Documentation

Public read-only JSON endpoints for AI Companion Picker community-pulse data. 9 platforms, no API key, CC BY 4.0 licensed. Methodology v1.0 disclosed and versioned.

Read this first

Every API response carries a _methodology_url and _methodology_version field. Before treating any number as ground truth, read the methodology page (currently v1.0) for data sources, classifier prompt, sample sizes, exclusion rules, and confidence-threshold logic.

Read methodology v1.0 →

Quick Start

Three endpoint families. All static JSON, served from Cloudflare CDN. No API key. Rate-limited at the edge by IP via cache.

# Index of all platforms with sufficient signal
GET https://aicompanionpicker.com/api/community-pulse/all-platforms.json

# Per-platform full history
GET https://aicompanionpicker.com/api/community-pulse/[platform].json

# Period-specific snapshot (immutable; cite this URL in stories)
GET https://aicompanionpicker.com/api/community-pulse/[platform]/[YYYY-MM].json

Endpoint Reference

GET /api/community-pulse/all-platforms.json

Returns the index of all platforms with sufficient signal (≥2 valid months in pulse history). Each entry carries a latest score, trend direction, and URLs into the per-platform endpoints.

Example response (truncated)

{
  "_source": "AI Companion Picker",
  "_license": "CC BY 4.0",
  "_methodology_url": "https://aicompanionpicker.com/about/methodology/",
  "_methodology_version": "v1.0",
  "_data_updated_at": "2026-05-01T08:15:04Z",
  "platforms_with_signal": 9,
  "platforms_tracked_total": 13,
  "refresh_cadence": "bi-weekly (1st and 15th of each month)",
  "platforms": [
    {
      "platform_id": "replika",
      "platform_name": "Replika",
      "latest_community_score": 3.0,
      "latest_month": "2026-06",
      "months_tracked": 6,
      "trend_direction": "declining",
      "full_history_url": "https://aicompanionpicker.com/api/community-pulse/replika.json",
      "latest_snapshot_url": "https://aicompanionpicker.com/api/community-pulse/replika/2026-06.json",
      "dashboard_url": "https://aicompanionpicker.com/community-ratings/dashboards/replika/"
    }
    /* ... 8 more entries ... */
  ]
}

GET /api/community-pulse/[platform].json

Full sentiment history for one platform across every valid month. Use the platforms_with_signal list from all-platforms.json to discover which slugs are valid.

Example response (truncated)

{
  "_source": "AI Companion Picker",
  "_methodology_version": "v1.0",
  "_data_updated_at": "2026-06-15T08:15:04Z",
  "platform_id": "replika",
  "platform_name": "Replika",
  "editor_score": 3.8,
  "months_tracked": 6,
  "trend": {
    "direction": "declining",
    "change_percent": -8.5,
    "months_tracked": 6
  },
  "monthly_scores": [
    {
      "month": "2026-01",
      "community_score": 3.2,
      "sample_size": { "reddit_threads": 15, "reddit_comments": 79, /* ... */ },
      "aspects": [
        { "name": "Character Quality", "score": 2.8 },
        { "name": "Pricing & Value", "score": 2.5 }
        /* ... 3 more aspects ... */
      ],
      "consensus": "..."
    }
    /* ... 5 more months ... */
  ]
}

GET /api/community-pulse/[platform]/[period].json

Single-month snapshot. Use this URL when citing in stories or papers. The dated URL is immutable; even if methodology revises, your citation still points to the data and methodology version that produced it. Period format: YYYY-MM.

Example response (truncated)

{
  "_source": "AI Companion Picker",
  "_methodology_version": "v1.0",
  "_data_updated_at": "2026-06-15T08:15:04Z",
  "_snapshot_url": "https://aicompanionpicker.com/api/community-pulse/replika/2026-06.json",
  "platform_id": "replika",
  "platform_name": "Replika",
  "editor_score": 3.8,
  "month": "2026-06",
  "community_score": 3.0,
  "sample_size": { /* per-source breakdown */ },
  "aspects": [ /* 5 aspect scores */ ],
  "consensus": "...",
  "classifier_model": "claude-haiku-4-5-20251001"
}

Response Metadata

Every endpoint returns these fields prefixed with _. Treat them as the contract: do not rely on field names that don’t start with _ being stable, but the _-prefixed metadata is.

Field	Meaning
_source	Always “AI Companion Picker”.
_license	“CC BY 4.0”. URL in `_license_url`.
_attribution_required	`true`. Required for license compliance.
_attribution_text	Pre-formatted attribution string for citations.
_methodology_url	Link to the methodology page.
_methodology_version	Lock to a specific methodology revision (e.g. `v1.0`).
_data_updated_at	ISO 8601 timestamp of the most recent classifier run for this payload.
_api_version	Major API revision. Currently `1`; breaking changes bump this.
_docs_url	Link back to this page.

Code Samples

curl

curl -s https://aicompanionpicker.com/api/community-pulse/replika.json | jq '.platform_name, .trend.direction, .monthly_scores[-1].community_score'

Python

import urllib.request, json

url = "https://aicompanionpicker.com/api/community-pulse/replika.json"
with urllib.request.urlopen(url) as r:
    data = json.load(r)

# Always check methodology version before drawing conclusions
print("methodology", data["_methodology_version"])
print(data["platform_name"], "trend:", data["trend"]["direction"])

# Latest community score
latest = data["monthly_scores"][-1]
print(latest["month"], "community_score:", latest["community_score"])

# Per-aspect breakdown for the latest month
for a in latest.get("aspects", []):
    print(f"  {a['name']}: {a['score']}")

JavaScript (Node 18+ / browser)

const url = "https://aicompanionpicker.com/api/community-pulse/replika.json";
const res = await fetch(url);
const data = await res.json();

console.log("methodology", data._methodology_version);
console.log(data.platform_name, "trend:", data.trend.direction);

const latest = data.monthly_scores.at(-1);
console.log(latest.month, "score:", latest.community_score);

Required Attribution

All API responses are licensed CC BY 4.0. Required for license compliance:

1. Dofollow link to aicompanionpicker.com on the surface where the data appears.
2. Methodology version cited (the _methodology_version field).
3. “Data as of [date]” reference matching the _data_updated_at field, OR the dated snapshot URL when citing a specific month.

The _attribution_text field on every response is pre-formatted and license-compliant. Copy it verbatim if in doubt.

Full license terms, plain-English summary, and acceptable/unacceptable use examples: /data/license/.

How to Cite This API

Inline prose

According to AI Companion Picker (methodology v1.0, data as of [date]), [specific finding from the data]. Source: https://aicompanionpicker.com/api/community-pulse/[platform]/[YYYY-MM].json

Caption attribution

Source: AI Companion Picker community pulse, methodology v1.0

HTML

<p>Data: <a href="https://aicompanionpicker.com/api/community-pulse/replika/2026-06.json">AI Companion Picker</a> (methodology v1.0, 2026-06)</p>

Markdown

Data: [AI Companion Picker](https://aicompanionpicker.com/api/community-pulse/replika/2026-06.json) (methodology v1.0, 2026-06)

More formats (BibTeX)

@misc{acp_replika_2026_06,
  author       = {AI Companion Picker},
  title        = {Replika Community Sentiment, 2026-06},
  year         = {2026},
  howpublished = {\url{https://aicompanionpicker.com/api/community-pulse/replika/2026-06.json}},
  note         = {Methodology v1.0}
}

Rate Limits & Cache

No API key, no per-request quota. The data is static JSON served from Cloudflare’s CDN; the cache absorbs typical access patterns. Endpoints carry a 1-hour edge cache (Cache-Control: public, max-age=3600).

The pipeline that produces this data refreshes bi-weekly (1st and 15th of each month). Polling more often than that gets cached responses; polling less often is fine. If you need real-time data, this isn’t the API for you — the underlying classifier and source aggregation make sub-day cadence economically and statistically unsound.

Building something that needs higher rate limits or webhook delivery? Email nolan@aicompanionpicker.com. A developer/partner tier is on the roadmap if usage justifies it.

Embeddable Chart Widgets

Pre-rendered, self-contained SVG charts. Embed via the “Embed this chart” button on any per-platform dashboard, or hand-roll an <img> against the URL pattern below. No iframes, no JS dependencies on partner sites — just an SVG with attribution metadata baked in.

URL pattern

GET /widgets/[platform]/[metric]/[period].svg

Metrics: sentiment (line chart), aspects (5-line breakdown).

Period values: all-time plus year-quarter (YYYY-qN, e.g. 2026-q2) and year-to-date (YYYY-ytd, e.g. 2026-ytd). New years and quarters auto-materialize as data accumulates. Slices only render when there are at least 2 valid data points in the range, so URL pattern is reliable but specific slices may 404 until they have enough data.

Embed code template (returned by the dashboard modal):

<div class="acp-widget" style="max-width:720px;margin:1em 0;font-family:system-ui,sans-serif;">
  <img src="https://aicompanionpicker.com/widgets/replika/sentiment/all-time.svg"
       alt="Replika community sentiment trend, All-time"
       style="width:100%;height:auto;display:block;" />
  <p style="font-size:0.75em;color:#555;margin:0.4em 0 0;">
    Data: <a href="https://aicompanionpicker.com/community-ratings/dashboards/replika/" rel="noopener">AI Companion Picker</a>
    &middot; <a href="https://aicompanionpicker.com/data/license/" rel="noopener">CC BY 4.0</a>
  </p>
</div>

The CC BY 4.0 license requires the attribution paragraph stays visible. Removing it violates the license.

Methodology v1.0

Sources, classifier prompt, sample sizes, exclusion rules

Data Hub

Technical raw access, license terms, planned CSV bulk downloads

Research Hub

Citation-ready summaries, named editor, key findings

Cite this

Pick a format. All citations reference methodology v1.1 so readers can verify your numbers.

Inline prose (best for newsroom drafting)

Loading...

More formats (BibTeX, direct image, share URL)

BibTeX is included for researcher / academic workflows. Direct image and share URL tabs are for cases where the host CMS is more comfortable with raw URLs than embed code.

All citations reference dated-snapshot URLs where available and include methodology version v1.1. Data licensed CC BY 4.0; attribution required (full terms).

Age Verification Required

API Documentation

Quick Start

Endpoint Reference

Response Metadata

Code Samples

Required Attribution

How to Cite This API

Rate Limits & Cache

Embeddable Chart Widgets

Methodology v1.0

Data Hub

Research Hub