Start with Search when you’re still shaping the problem.

• Use POST /v3/search/documents when you need full records (titles, text, metadata) to inspect or pass along.
• Use POST /v3/search/aggregations when you only need counts, facets, and quick "how big/how often" signals to steer filters and UI. Returns no documents, just metrics. If you'll run downstream analyses, freeze scope into a Document Set so later assets operate over a stable, reproducible body of content.

Use a Document Set to freeze the scope so every downstream asset runs over the same content. You can create one in two common ways:

• From search terms — POST /v3/document-sets with a search_request. The response returns a document_set_id you’ll pass to assets.
• From raw text — POST /v3/document-sets with a raw_texts array of strings. Each string is treated as one document in the set. Not all endpoints support raw text, so check the documentation for the individual endpoints.

Why it matters: with a fixed document_set_id, assets are deterministic and auditable, rather than chasing a moving search window.

You can programmatically list your sets later via GET /v3/document-sets and inspect basic metadata (name, created_at).

These endpoints help you move from "a heap of articles" to "what claims are being made, how they group, and how they evolve."

• Narratives — Combine related claims into narrative-level assets with LLM-generated titles, date-aware summaries, citations back to source chunks, and per-entity sentiment so you can inspect how a specific storyline is supported across documents.
• Themes — Automatically cluster extracted claims into narratives and then higher-level themes so you can see the major topics, perspectives, entities, and time ranges that structure a document set.
• Theme Sets — Generate theme-level titles and summaries for curated groups of narratives, reusing their titles and summaries to synthesize an overarching perspective for the cluster you care about, rather than one discovered automatically.

Tip: Treat these as asynchronous assets: create, poll until complete, then fetch results. This keeps calls responsive and lets you orchestrate multiple analyses in parallel.

Move from "who is this?" to "show me evidence." These endpoints help you discover canonical IDs, build a reusable lookup, and then generate cited facts, affiliations, and quotes over your scoped body of content.

• Find canonical IDs (Knowledge Base search)
  
  • GET /v3/knowledge-base/entities-search
  • Fuzzy, alias-aware search over the NEL (named entity linking) KB. Filter by entity_types, paginate with 1-based page and page_size (max 100). Results are relevance-ranked.
• Build the foundation (Entity Lookup asset)
  
  • POST /v3/assets/entity-lookup
  • Creates a comprehensive lookup of entities and sentence-level co-mentions for your Document Set; many downstream entity calculators depend on this asset. Requires document_set_id. Read results with GET /v3/assets/entity-lookup/{asset_id}/results (paginated; up to 1000 items/page) to fetch entities, relationships, and context.
• Summarize with citations (Entity Summary)
  
  • POST /v3/assets/entity-summary
  • Generates a concise, evidence-linked sentence about an entity (or an entity pair) with structured references. If you don’t pass an entity_lookup_asset_id, one is auto-created.
• Extract affiliations (Entity Affiliations)
  
  • POST /v3/assets/entity-affiliations
  • Pulls roles/positions/org relationships and returns per-document sentence-level citations. Depends on Entity Lookup (auto-created if missing). Results are paginated (asset results endpoints typically allow large pages, for example, up to 1000).
• Attribute quotes (Entity Quotes)
  
  • POST /v3/assets/entity-quotes
  • Finds quoted text and attributes it to the target entity, returning document IDs, sentence content, and character spans. Depends on Entity Lookup (auto-created if missing). Read with GET /v3/assets/entity-quotes/{asset_id}/results (paginated).

• Targeted Sentiment – Analyze up to 20 short documents from a Document Set to extract entities, attach positive / neutral / negative stance labels, and return character spans for each mention, making it easy to rapidly triage per-entity sentiment in inbox-sized batches.
• Targeted Sentiment Counts – Run the same entity-level sentiment analysis but aggregate all positive, neutral, and negative mentions per entity across up to 20 documents, returning grouped spans so you can see not just stance but how often each sentiment occurs.