API and MCP server

Endpoints

• GET /api/v1/decisions

  Keyword search with the explorer's filters: q, outcome, field, failed (prong), obj (objection slug), stage, ev (evidence theme, e.g. rfe or noid), era, kind, niw, from, to, page. 20 results a page.

  /api/v1/decisions?niw=1&failed=prong2&q=generic%20letters
• GET /api/v1/decisions/{id}

  One decision: metadata, prongs met and not met, objection tags with the sentence and page each was matched on, and authorities cited.

  /api/v1/decisions/AUG172026_01B5203
• GET /api/v1/objections

  The objection catalog, with how often each was raised in NIW appeals decided under Dhanasar.

  /api/v1/objections
• GET /api/v1/stats

  Corpus size, date range, newest NIW appeal, and how often each prong was found not met.

  /api/v1/stats

Every response has the same shape:

{ "data": { ... }, "meta": { "source": "https://petitionlens.org", "docs": "https://petitionlens.org/developers", "notice": "..." } }

MCP server

Four read-only tools: search_decisions, get_decision, list_objections and get_stats. The server calls this API; it holds no data of its own. Add it to your MCP client's config:

{
  "mcpServers": {
    "petitionlens": {
      "command": "npx",
      "args": [
        "tsx",
        "<path-to-PetitionLens>/apps/mcp/src/index.ts"
      ],
      "env": {
        "PETITIONLENS_URL": "https://petitionlens.org"
      }
    }
  }
}

Licence and reuse

The data comes in two layers, and only one of them is ours. The decision texts are U.S. government works in the public domain — we claim nothing over them, and you can get them from USCIS directly. The annotations we derived (objection tags with their evidence sentences, prong findings, countries named, cleaned occupation labels) and this collection as a database are licensed CC-BY-4.0: reuse them, commercially or not, with credit.

Credit us as:

Data: PetitionLens (https://petitionlens.org), CC BY 4.0. Decisions: USCIS Administrative Appeals Office, public domain.

There is no crawler block on this site, and we would rather you used the API or the MCP server than scraped the HTML: it is faster for you and cheaper for us. If you need more than 60 requests a minute, ask us rather than spreading the load across addresses.