# 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_...`.
## 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?** Use the `urlSlug` when you want quick and memorable: it is stable in practice and only changes if an entity is genuinely renamed. For long-lived references, like a product tracker that must keep working across renames, store the entity `id` in its URL-safe dashed form (replace `/` with `-`, for example `kb-person-65`): it is permanent and never changes. Both forms are accepted anywhere an `{entityId}` is expected.

**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
  }
]
```

| 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 |

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

---

## 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/)