The data model: grants, contracts, funders and one response envelope

Every screen in a funding portal is built from three object types and one response envelope. Learn those four shapes well and the rest of this course is plumbing.

This lesson covers what the OpenGrants API returns, how it authenticates, how it fails, and how to wrap all of it in a small typed client that every later lesson imports. The client matters more than it looks: when a field name or parameter changes, you fix one file instead of hunting through route handlers.

The API at a glance

The OpenGrants API is a REST API over the same index the OpenGrants app searches: 139,000+ indexed funding opportunities, 43,000+ of them open, drawn from Grants.gov, SAM.gov, state and municipal portals and IRS 990 filings, refreshed daily. It is published with an OpenAPI 3.0.3 spec.

Seven endpoints accept an API key:

That is the whole surface. Search, filtering, sorting and paging are query parameters on the three list endpoints. Matching is the one POST. Webhooks (Lesson 4) push to you rather than being called.

Authentication

Keys are opaque strings, not JWTs. OpenGrants’ own agent documentation describes them as 40 characters. You create them in the Developer Dashboard, name them (“Production portal”, “Local dev”), and see each key exactly once, at creation. The dashboard afterward shows only a prefix, a created date and a last-used date.

curl -sS "https://ops.opengrants.io/functions/v1/grants-api?limit=1" \
  -H "Authorization: Bearer $OPENGRANTS_API_KEY"

Three rules follow from “you see it once”:

1. Create one key per environment. Local development, staging and production each get their own. When one leaks, you revoke one.
2. Store it in a secret manager the moment you copy it. On Cloudflare Workers that is npx wrangler secret put OPENGRANTS_API_KEY. Lesson 7 covers the full setup.
3. The key never reaches a browser. Not in a bundle, not in a NEXT_PUBLIC_ variable, not in a query string. The API sends Access-Control-Allow-Origin: *, so a browser call would technically work, and that is exactly why you must not do it: anyone who opens dev tools gets your unlimited-request key. Every call in this course goes through your server.

The response envelope

All three list endpoints return the same shape:

interface ListResponse<T> {
  results: T[];
  pagination: { total: number; limit: number; offset: number; returned: number };
  meta: { response_time_ms: number; sort_by: string; order: "asc" | "desc" };
}

Each field has a job in your UI:

• pagination.total is the count for the whole filter set. Render “Showing 20 of 1,284” without a second call.
• pagination.returned is separate from limit. When offset + returned >= total, you are on the last page. Do not infer the end from returned < limit; use the arithmetic.
• meta.sort_by and meta.order echo what the server actually applied. If you asked for sort_by=deadline_date and meta.sort_by says created_at, your query builder has a bug, and the response told you before a user did.
• meta.response_time_ms is server time. Log it next to your own round-trip time; the difference is network and your code.

Live responses also carry meta.search_mode, which is not in the documented interface. Treat any undocumented field as optional in your types.

Two responses do not use this envelope:

• count_only=true on a list endpoint returns only { total }. Use it for badge counts and dashboards.
• POST /match-grants-api returns { count, matches }. Lesson 3 covers it. Code that assumes every response has results will break on matching, which is a good reason to type the two shapes separately.

Paging limits

limit runs from 1 to 100 (default 20). offset is capped at 10,000. So the deepest you can page into any single filter set is about 10,100 records. That is not a problem for a portal, because no person pages that deep. It is a problem for anyone trying to mirror the index with a paging loop. If you think you need to walk everything, you almost certainly need a narrower filter, count_only, or webhooks instead.

The three objects

Grant

interface Grant {
  id: string;                 // UUID
  title: string;
  description: string;
  amount_min: number | null;
  amount_max: number | null;
  deadline_date: string | null; // ISO date
  status: string;
  geography: string | null;
  funder_id: string;
  funder_name: string;
  listing_url: string | null;
  created_at: string;         // ISO datetime
  categories: string[];
}

Contract

A contract carries everything a grant does, plus four fields that matter for government contracting:

For federal notices, listing_url points at the SAM.gov notice. funder_name carries the agency path, for example DEPT OF DEFENSE > DEPT OF THE NAVY.

Funder

Funder records are lighter: id, name, summary, website, created_at. Live responses also include a slug. Grants and contracts point back to their funder with funder_id and funder_name.

Fields you will see that the docs do not list

Querying live data shows a few extra fields on grants and contracts: opportunity_type (for example "open_opportunity"), project_end_date, and, on semantic or hybrid searches, relevance, a normalized 0 to 1 similarity score described in the API changelog. Model them as optional so your code survives either way.

Nulls are information

The most common data-model bug in funding portals is treating null as zero or as “soon.” Decide what each null means on screen before you write a component.

The amount filters interact with these nulls in a way that surprises people. From the docs: min_amount filters on amount_max, and max_amount filters on amount_min. So min_amount=250000 means “the award can reach at least $250,000.” That is the right semantics for “show me programs big enough for this project,” and it also means a record with no stated amounts will not match an amount filter. If your users care about completeness, offer the amount filter as an option, not a default.

Open, awarded, and the default you should keep

Since the API changelog entry of 2026-06-11, list endpoints return open opportunities only unless you ask otherwise. The opportunity_type parameter takes:

• open (default): applyable opportunities.
• awarded: previously funded projects, for research. These have no deadline; they carry project_end_date instead.
• all: both.

Keep the default for anything a member will act on. Use awarded for a separate “who has been funded for this kind of work” research view, and label it loudly. Mixing awarded records into a list people apply from is a support ticket waiting to happen.

Errors, and what each one is telling you

Errors come back as JSON with a stable machine code and a request ID:

{ "error": "Missing or invalid Authorization header", "code": "INVALID_API_KEY", "request_id": "9b891cf7-..." }

The two different 401s are worth memorizing. OpenGrants documents the distinction explicitly: a body with INVALID_API_KEY came from OpenGrants’ key validator; a body with UNAUTHORIZED_INVALID_JWT_FORMAT came from the gateway in front of it, which means you called a path that expects a session token. Read the body, not just the status.

Log request_id on every failure. It is the one value support can use to find your request.

Rate limits

The Developer tier is unlimited, and responses still carry X-RateLimit-Limit (-1 means unlimited) and X-RateLimit-Remaining. Write your client as if the API were metered anyway: retry only on 429 and 5xx, with exponential backoff, and cap the retries. That habit protects you from your own bugs (an infinite render loop firing requests) as much as from the API.

The typed client

Everything above goes into one file, src/lib/opengrants.ts. The full listing is in the starter template; the core looks like this:

export const OPENGRANTS_BASE_URL = "https://ops.opengrants.io/functions/v1";

export class OpenGrantsClient {
  constructor(private readonly apiKey: string, options: ClientOptions = {}) { /* ... */ }

  searchGrants(query: OpportunityQuery = {}): Promise<ListResponse<Grant>> {
    return this.request("/grants-api", { query: { ...query } });
  }
  countGrants(query: OpportunityQuery = {}): Promise<CountResponse> {
    return this.request("/grants-api", { query: { ...query, count_only: true } });
  }
  searchContracts(query: ContractQuery = {}): Promise<ListResponse<Contract>> {
    return this.request("/contracts-api", { query: { ...query } });
  }
  searchFunders(query: FunderQuery = {}): Promise<ListResponse<Funder>> {
    return this.request("/funders-api", { query: { ...query } });
  }
  matchGrants(req: MatchRequest): Promise<MatchResponse> {
    return this.request("/match-grants-api", { method: "POST", body: req });
  }
  // getGrant, getContract, getFunder, countContracts ...
}

The private request method does four things: serializes arrays like states: ["OR", "WA"] into states=OR,WA, drops undefined parameters, retries 429 and 5xx twice with backoff, and throws an OpenGrantsError carrying status, code, requestId and detail. Route handlers catch that one error type and never parse raw responses themselves.

One deliberate hedge: the docs describe the single-record endpoints as returning “one grant” but do not show whether the object comes bare or wrapped. The client’s unwrapOne accepts a bare object or a { data } or { result } wrapper. Once you have seen a real response, delete the branch you do not need.

const og = new OpenGrantsClient(env.OPENGRANTS_API_KEY);
const { total } = await og.countGrants({ states: ["OR"], include_national: true });

Common mistakes