How to use

There are three ways to put the Verdict Engine to work, depending on whether you want it applied to our stream or to your own text.

1. The feed — scored for you

Every item in the feed is already scored by the Verdict Engine the moment it's ingested. You don't call anything — actionability and sentiment ride along on each item.

In the app's live feed you can:

• read the actionability and sentiment badges on every row,
• filter to actionable only, or bound the sentiment range,
• narrow by ticker, source, and time.

Programmatically, the same scores are on every feed item via GET /v1/feeds:

# Actionable NVDA items, most bullish first
curl "https://api.forecite.dev/v1/feeds?symbol=NVDA&actionability=true&sentiment_min=7" \
  -H "Authorization: Bearer fc_live_your_key_here"

Use this when you want a continuously scored stream of the news Forecite already ingests — no scoring calls of your own.

2. Warren AI — score by conversation

Warren is Forecite's AI analyst. Paste a document into the chat — an article, a filing excerpt, a transcript, a tweet — and Warren runs it through the Verdict Engine and returns a score card with the full sub-score breakdown.

"Score this against TSLA: Tesla cuts Q1 Cybertruck production target to ~6k units…"

Behind the scenes Warren calls the Verdict Engine as a tool, scores the artifact (both heads, so you always see the sentiment read), and renders the actionability and sentiment sub-scores inline. Use this for ad-hoc, exploratory scoring where you want the reasoning in plain language alongside the numbers.

3. The scoring API — score your own artifacts

To run the Verdict Engine on your own text programmatically, call POST /v1/score. This is the right choice for internal research pipelines, a source Forecite doesn't ingest, or batch scoring.

curl https://api.forecite.dev/v1/score \
  -H "Authorization: Bearer fc_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "artifact": {
      "type": "filing",
      "title": "Acme cuts FY guide on softening demand",
      "body": "Acme Corp lowered its full-year revenue outlook...",
      "related_symbols": ["ACME"]
    },
    "options": { "model": "pro", "score_sentiment": "if_actionable" }
  }'

const res = await fetch("https://api.forecite.dev/v1/score", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FORECITE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    artifact: {
      type: "filing",
      title: "Acme cuts FY guide on softening demand",
      body: "Acme Corp lowered its full-year revenue outlook...",
      related_symbols: ["ACME"],
    },
    options: { model: "pro", score_sentiment: "if_actionable" },
  }),
})
const verdict = await res.json()

import os, requests

verdict = requests.post(
    "https://api.forecite.dev/v1/score",
    headers={"Authorization": f"Bearer {os.environ['FORECITE_API_KEY']}"},
    json={
        "artifact": {
            "type": "filing",
            "title": "Acme cuts FY guide on softening demand",
            "body": "Acme Corp lowered its full-year revenue outlook...",
            "related_symbols": ["ACME"],
        },
        "options": {"model": "pro", "score_sentiment": "if_actionable"},
    },
).json()

Options worth knowing

See the /v1/score reference for the full request and response schema, and Rate limits for per-plan scoring quotas.