№ 02 — Developer API

Partner API v1

A clean, read-only JSON API over Common.Vision's analyzed news corpus — articles with AI summaries, tags, entities and sentiment; feeds; trending topics; and product mentions.

Base URL

https://common.vision/api/v1

Auth

Bearer token

Format

JSON

Getting started

How to get an API token

API access is granted to partners, and partner signup is invite-only. With a valid invite code, creating an account issues your first token instantly — no waiting on approval.

1

Get an invite code, then create a partner account. Partner signup requires an invite code — request one if you don't have it. Then go to partner signup and register your organization. You become your team's first admin.
2

Copy your first token — it's shown once. Right after signup you land on the tokens page with your plaintext token in a copy-once banner. Store it somewhere safe (a secrets manager); it is never displayed again.
3

Manage tokens any time. From your partner dashboard → Manage API tokens you can generate additional tokens, rotate, or revoke them. Revoking takes effect immediately.

Create a partner account →

Authentication

Authenticating requests

Send your token in the Authorization header on every request.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Accept: application/json" \
     "https://common.vision/api/v1/articles"

Status	Meaning
401	Missing or invalid token
403	Token revoked or partner inactive
429	Rate limit exceeded — slow down

Rate limits

Tiers

Limits are per token, per minute. New partners start on Free; higher tiers are available from your partner billing page.

Tier	Requests / minute
Free	30
Standard	120
Premium	300

Data model

Commons vs. Account Feeds

Article and feed endpoints accept a corpus parameter that selects which body of content you read:

corpus	Returns
commons	The public Commons corpus (default).
account	Only your partner's private Account Feeds (your “Beat”).
all	Commons + your Account Feeds, merged.

Account Feeds are private feeds you add to your own corpus (e.g. via an OPML upload on your partner dashboard). They are only ever visible to your token — never leaked into the public Commons.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://common.vision/api/v1/articles?corpus=all&per_page=20"

Reference

Endpoints

Articles

GET /articles

Paginated articles. Filters: tags, entities, sentiment (positive|negative|neutral), impact (low|medium|high), from, to, search, feed_id, corpus, page, per_page (max 100).

GET /articles/{slug}

A single article by slug.

GET /articles/related

Articles related to a source url (required) by tag/entity overlap. limit max 50.

Example response

{
  "data": [
    {
      "id": 123,
      "slug": "revolutionary-ai-breakthrough",
      "title": "Revolutionary AI Breakthrough Announced",
      "summary": "AI-generated summary of the article...",
      "url": "https://source.com/article",
      "published_at": "2026-06-24T10:30:00+00:00",
      "tags": ["AI", "Technology"],
      "entities": ["OpenAI", "Broadcom"],
      "sentiment": { "tone_class": "informative", "emotional_weight": 0.3, "human_impact_score": 7 },
      "feed": { "id": 45, "name": "Tech News Daily", "feed_type": "rss" }
    }
  ],
  "meta": { "total": 1523, "per_page": 25, "current_page": 1, "last_page": 61 },
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." }
}

Feeds

GET /feeds

Active feeds. Filters: type (rss|atom|json), limit (max 100), corpus.

GET /feeds/{id}

A single feed by ID.

GET /feeds/{id}/articles

Articles from one feed — accepts all the /articles filters.

Products

GET /products/mentions

Articles mentioning tracked products. Supports timeframe=all.

GET /products/popular

Most-mentioned products over a timeframe.

Error handling

Errors

Errors return a JSON body with a message and the appropriate HTTP status. Common cases:

401 / 403	Authentication problem (see above)
404	Resource not found
422	Invalid or missing parameters
429	Rate limit exceeded

Ready to build?

Create a partner account and your first token is waiting on the other side.

Get API access →