# Entities API

> Search the SentiSense ontology for the people, companies, products, and organizations we track, and query their SentiSense Score, sentiment, and mentions.

Base URL: `https://app.sentisense.ai/api/v1/kb`
Tier: Free (API key required)

All API access requires an API key via the `X-SentiSense-API-Key` header. Keys look like `ss_live_...`.

> SDKs: [Python](https://github.com/SentiSenseApp/sentisense#knowledge-base) · [Node](https://github.com/SentiSenseApp/sentisense-node#knowledge-base)

## Overview

The SentiSense ontology tracks not just stocks but the people, products, and organizations that move them: executives, politicians, central bankers, flagship products, regulators. Every one of them has the same metrics surface as a stock: the SentiSense Score, sentiment, mentions, and social dominance time series from the [Metrics API](/docs/api/metrics/).

This page documents how to find an entity's handle. The returned `urlSlug` (or `ticker`) plugs straight into the Metrics API `{entityId}` parameter.

The `urlSlug` is also the web handle: `https://app.sentisense.ai/entities/{urlSlug}` opens that entity in the app, for example [Anthropic](https://app.sentisense.ai/entities/Anthropic) or [ChatGPT](https://app.sentisense.ai/entities/ChatGPT).

**Which handle should you store?** The `urlSlug`, or the `ticker` for a listed company. It is the only identifier the API accepts anywhere an `{entityId}` is expected, and it is stable in practice: it changes only if an entity is genuinely renamed. Internal KB ids, including the dashed `kb-person-65` form, are not part of the public API and resolve to nothing here. If a rename ever breaks a stored handle, `GET /api/v1/kb/entities/search?q=` finds the entity again by name.

**What you can build with this:**

- **Track a person's SentiSense Score.** How is the market conversation on Jerome Powell trending this month?
- **Watch a politician's sentiment around a trade disclosure.** Nancy Pelosi's sentiment and mention volume, day by day.
- **Compare an executive against their company.** Does the crowd feel differently about Jensen Huang than about NVDA?
- **Follow a product, not just its maker.** Mentions of a flagship product can move before the parent ticker does.

**Access:** API key required, available on every tier. Requests count against your monthly quota and per-minute rate limit.

> **Building an AI agent?** See [Entity sentiment API: track sentiment for CEOs, politicians, and products](/blog/entity-sentiment-api-beyond-tickers/) for a worked end-to-end example: search a person by name, then pull their sentiment time series with the handle you get back.

---

## GET /entities/search

Returns the best-matching entities for a query, scored across names, aliases, tickers, and slugs (exact matches first, then prefix, then substring).

This is a resolution endpoint, not an enumeration one: queries must be at least 2 characters and results are capped, so you look up entities you already know about rather than paging through the catalog.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `q` | string | Yes | - | Case-insensitive name, alias, ticker, or slug fragment (minimum 2 characters) |
| `type` | string | No | all | Filter: `company`, `country`, `etf`, `organization`, `person`, `product`, `topic` |
| `limit` | int | No | 10 | Maximum results (capped at 25) |

**Example Request:**

```bash
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/kb/entities/search?q=pelosi&type=person"
```

**Response:** array of matches, best first:

```json
[
  {
    "name": "Nancy Pelosi",
    "urlSlug": "Nancy-Pelosi",
    "type": "person",
    "ticker": null
  }
]
```

A company match carries two extra fields:

```json
[
  {
    "name": "Samsung Electronics Co., Ltd.",
    "urlSlug": "Samsung-Electronics-Co-Ltd",
    "type": "company",
    "ticker": null,
    "listingCoverage": "public_untracked",
    "listing": "KRX: 005930"
  }
]
```

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Display name |
| `urlSlug` | string | Canonical handle for the Metrics API `{entityId}` parameter |
| `type` | string | `company`, `country`, `etf`, `organization`, `person`, `product`, or `topic` |
| `ticker` | string\|null | Primary ticker for companies and ETFs; `null` otherwise |
| `listingCoverage` | string \| absent | Companies only: `public_tracked` (listed on a market we price), `public_untracked` (listed on a market we do not price), or `private` (not listed). Absent for every other entity type |
| `listing` | string \| absent | The untracked listing as one string, e.g. `"KRX: 005930"`. Present only alongside `listingCoverage: "public_untracked"` |

A `public_untracked` company has no ticker, no price series and no `/stocks/{ticker}` page; it can still be searched and queried for sentiment, mentions and Score, and `listing` is what to show in place of a ticker.

Returns `400 invalid_parameter` when `q` is under 2 characters or `type` is not one of the listed values.

`listingCoverage` is a different question from `listingStatus` on [GET /stocks/{ticker}/price](/docs/api/stocks/), which is the delisting lifecycle (`DELISTED`, `PENDING_DELISTING`) of a symbol we do price.

---

## GET /entities/popular

Returns a small curated list of high-profile entities (major CEOs, political figures, the Federal Reserve). Useful as a seed list for autocomplete or a "trending people" widget without issuing a search.

**Example Request:**

```bash
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/kb/entities/popular"
```

**Response:** array of entities. Each entry:

| Field | Type | Description |
|-------|------|-------------|
| `displayName` | string | Entity display name |
| `type` | string | `PERSON`, `ORGANIZATION`, etc. |
| `urlSlug` | string\|null | Handle for the Metrics API `{entityId}` parameter |
| `relatedStock` | string\|null | Ticker of the most closely associated stock, when there is one |

---

## Worked examples

**Check a person's SentiSense Score.** Resolve the handle once, then query any metric:

```bash
# 1. Resolve the handle
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/kb/entities/search?q=jensen%20huang"
# -> [{"name": "Jensen Huang", "urlSlug": "Jensen-Huang", "type": "person", "ticker": null}]

# 2. SentiSense Score time series for that person
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v2/metrics/entity/Jensen-Huang/metric/sentisense"
```

**Politician sentiment and mention volume:**

```bash
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v2/metrics/entity/Nancy-Pelosi/metric/sentiment"
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v2/metrics/entity/Nancy-Pelosi/metric/mentions"
```

**Executive vs company.** Same metric, two handles, one comparison:

```bash
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v2/metrics/entity/Jensen-Huang/metric/sentiment"
curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v2/metrics/entity/NVDA/metric/sentiment"
```

The metric response format (time-ordered points with a flat `value` scalar) is documented in the [Metrics API](/docs/api/metrics/).

**Related discovery surfaces:**
- `GET /api/v1/stocks/{ticker}/entities`: the entities related to one stock (executives, products), each carrying its `urlSlug` (see the [Stocks API](/docs/api/stocks/))
- Identifier semantics across all endpoints: the Entity Identifiers section of the [API Overview](/docs/api/)
- How a name resolves to one typed node, with the calls that read the graph: [the knowledge graph behind stock sentiment](/blog/knowledge-graph-behind-stock-sentiment/)