# Topics

Extract the concepts that matter for a query, each with the evidence behind it.

## Endpoints

| Method | Path | Scope | Credits | Description |
|---|---|---|---|---|
| POST | `/v1/topic-searches` | `topics:write` | 4 / 12 by depth | Create (async) |
| GET | `/v1/topic-searches/{id}` | `topics:read` | 0 | Retrieve topics + evidence |

> [!info] This endpoint is asynchronous
> Returns `202`; poll or use a webhook.

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | The area to map |
| `max_topics` | integer | no | Default 5, maximum 20 |
| `language` | string | no | |

## Response

```json
{
  "object": "topic_search",
  "id": "tsrch_3pcptfwlcv",
  "status": "succeeded",
  "query": "How does climate change affect biodiversity?",
  "topic_count": 3,
  "credits_cost": 4,
  "topics": [
    {
      "object": "topic",
      "id": "top_2808be1c6d",
      "name": "Range shifts",
      "description": "Poleward and upslope movement of species distributions tracking isotherms.",
      "evidence": [
        {
          "quote": "Species have shifted their ranges poleward by 16.9 km per decade on average.",
          "source": {
            "type": "paper",
            "id": "pap_3kf9wq2m8x",
            "title": "Climate-driven range shifts"
          },
          "locations": [
            {
              "page": 2,
              "bbox": {
                "x": 0.11,
                "y": 0.55,
                "width": 0.78,
                "height": 0.03
              }
            }
          ]
        }
      ]
    },
    {
      "object": "topic",
      "id": "top_91ad4fe07b",
      "name": "Phenological mismatch",
      "description": "Decoupling of seasonal timing between interacting species.",
      "evidence": [
        {
          "quote": "Budburst advanced 8 days while caterpillar emergence advanced 15.",
          "source": {
            "type": "paper",
            "id": "pap_6wq0nc2v8t",
            "title": "Trophic asynchrony under warming"
          },
          "locations": [
            {
              "page": 6,
              "bbox": {}
            }
          ]
        }
      ]
    },
    {
      "object": "topic",
      "id": "top_5cd10ba934",
      "name": "Ocean deoxygenation",
      "description": "Falling dissolved oxygen compressing viable habitat for large pelagic species.",
      "evidence": [
        {
          "quote": null,
          "source": {
            "type": "model"
          },
          "locations": []
        }
      ]
    }
  ]
}
```

**Topics are ordered by evidential weight**, strongest first — not alphabetically, and not by
frequency. The ordering is stable for a given query.

| Field | Type | Description |
|---|---|---|
| `topics[].name` | string | Two or three words. Suitable as a facet label |
| `topics[].description` | string | One sentence, in the literature's own vocabulary |
| `topics[].evidence[]` | array | Supporting spans. May be empty — see below |
| `topics[].evidence[].quote` | string | Verbatim from the source. `null` when `source.type` is `model` |
| `topics[].evidence[].source.type` | enum | `paper`, `document`, or `model` |

## Topics sourced from the model

The third topic above has `source.type: "model"` and no quote. That means the topic was inferred
from the shape of the result set rather than lifted from any single paper — a real pattern the
corpus supports collectively, but with no one passage to point at.

Treat these as **suggestions, not findings**:

- Never render them with the citation affordance you use for `paper` and `document` evidence.
- Label them in the UI. "Suggested by SciSpace" is honest; silence is not.
- Exclude them from systematic-review pipelines, where every row needs a locator.

```python
grounded = [t for t in topic_search.topics
            if any(e.source.type != "model" for e in t.evidence)]
```

## Use cases

- Query expansion before a search
- Taxonomy or landscape mapping
- Gap-finding: topics with thin evidence are where the literature is quiet

## Related

topic · searches