---
name: 1stauthor-grants
description: The 1stAuthor grants domain.
---

# 1stAuthor Grants

1,328,138 research awards: 651,041 NSF awards (one per award id), 570,238 NIH RePORTER projects (multi-year funding merged per core project number, with per-year amounts) and 106,859 EU CORDIS projects (FP5 to Horizon Europe, amounts in EUR). Organisation / country / PI / directorate / activity code / dates / amounts come from the source; topics, methods, domain and one-line summaries are model-generated (title-only where no abstract exists — see _enrich.basis).

Base URL `https://api.1stauthor.com`. Every call takes `Authorization: Bearer $FA_API_KEY`; the free samples named below work without a key. Free sample id: `nih:R25HG007515`, free sample query: `single cell transcriptomics`.

## Three verbs, every domain

```
POST /v1/{domain}/search  {query, filters?, top_k?}      → hits[].id + a card each
GET  /v1/{domain}/read/{id}?level=brief|detail|full      → read as deep as you need
POST /v1/{domain}/ask     {query, effort: low|medium|high} → an answer with real citations
```

`read` also takes `extra=<side>` for another side of the same document and `format=json|md|html`.
At `level=full`, `section=<name>` reads one section and `characters=N` the first N characters.

## Start here

- **Find awards** — `POST /v1/grants/search {"query": "单细胞转录组", "filters": {"agency": "nih", "fy": {"gte": 2020}}}`
- **Read one award** — `GET /v1/grants/read/nih:R25HG007515`
- **Counts per institute** — `GET /v1/grants/facets?field=ic_or_directorate`

## Search filters

| field | type | meaning |
|---|---|---|
| `agency` | keyword · eq any | Funding agency |
| `research_domain` | keyword · eq any | Research domain (model-assigned, closed set of 13) |
| `ic_or_directorate` | keyword · eq any | NIH institute, NSF directorate or CORDIS framework programme (FP7 / H2020 / HORIZON …, see facets) |
| `activity_code` | keyword · eq any | Funding mechanism: NIH activity code (R01 / R21 / F32 …), NSF award type or CORDIS funding scheme |
| `fy` | integer · eq range | Fiscal year, range |
| `start_year` | integer · eq range | Project start year, range |
| `end_year` | integer · eq range | Project end year, range |
| `amount_total` | number · eq range | Total amount, range (USD for NIH / NSF; EU contribution in EUR for CORDIS — pair with agency when filtering across agencies) |
| `org_country` | keyword · eq any | Organisation country (source casing is inconsistent — see notes) |

Rarely needed, but valid: `org_state`, `org_name`, `pi_names`, `topics`, `programs`, `core_project_num`, `is_renewal`.

Filters combine with AND; `_or` / `_not` are available. Ranges are `{"gte": n}` / `{"lte": n}`, full text is `{"text": "…"}`.

## Read

| level | credits | returns |
|---|---|---|
| `brief` | 1 | Card: the fields needed to triage, same as in search hits |
| `detail` (default) | 2 | Every structured field (rule-derived plus model-generated; model fields are listed in _enrich.fields) |
| `full` | 5 | Full text (not available yet: abstracts are already in level=detail; progress reports and publications are not in this corpus) |

## Ask

`POST /v1/grants/ask {query, effort}` — Agentic Q&A over this domain: the model turns the question into filters plus keywords from the domain's own self-description, reads the hits and answers with [grants:<grant_id> <title>] citations; /stream is NDJSON with real token deltas. Costs 50 / 100 / 200 credits by effort. Append `/stream` for NDJSON; the first event is always `billing`.

`sources` is the retrieval set, not the citation list — filter it by the ids that appear in `answer`. `answer_truncated` means the answer is incomplete; say so.

## Also here

- GET /v1/entities?q=<机构名> → 实体；GET /v1/entities/<id>/docs?domain=grants → 该机构在本域的文档

## Facets

`GET /v1/grants/facets?field=<field>` lists the legal values for `agency`, `research_domain`, `ic_or_directorate`, `activity_code`, `org_country`, `org_state` — free, no key. Use it instead of guessing a spelling.

## Working rules

- **Search first, read second.** A search hit is a card; decide from the card which ids deserve a read.
- **Read in layers.** `detail` answers most questions; go to `full` only when the answer is not in it.
- **Filters are declared.** An undeclared filter field is a 400, never a silent no-op. `GET /v1/{domain}` lists what exists.
- **Cite what you read.** Use the citation format below, and say plainly when the corpus has nothing.
- **Failures are not charged.** A 404 costs nothing; an upstream error is refunded. Quote `meta.request_id` when reporting one.

Citation format: `[NIH R25HG007515]`.

## What this corpus will and will not tell you

- One NIH document = all yearly awards under a core project number (amount_total is the sum, funding_by_year the breakdown); one NSF document = one award; one CORDIS document = one project (grant_id = cordis:<project id>), org_* is the coordinator and amount_total the EU contribution in EUR (currency=EUR at level=head; NIH / NSF have no currency field and are in USD).
- org_country casing is inconsistent in the source (both UNITED STATES and United States, 1.088M awards) — pass both spellings.
- `topics` are open labels with tens of thousands of values: good to read, poor to filter on — use research_domain.
- Where no abstract exists the summary comes from the title alone (_enrich.basis=title_only).
- The index holds no full text: level=full is not available yet (abstracts are already in level=detail; progress reports and publications are not in this corpus).

---

Generated from https://api.1stauthor.com/v1/grants on 2026-10-14. Full reference: https://1stauthor.com/docs/grants/