@Billy and I spent some time today looking into the issues that folks have been having with the API and we believe that we came out of it with some tips and helpful advice for what folks are running into.
Authentication
One of the first things that folks have noted issues with is authentication failures. Please make sure that you are using the X-Auth key and not the " ApiJwtAuth. The Jwt auth endpoint is used internally, and is still not fully implemented. Using this endpoint can result in authentication failures.
Also please remember that the API is a POST, not a GET.
A successful authentication in Postman would look like:
Type: API Key
Key: X-Auth
Value: (API Key)
Add to: Header
Body
If folks are having issues with body, please make sure that it is in raw JSON format.
A successful body in Postman would look like:
raw
JSON
Body:
{
"pagination": {
"page_offset": 1,
"page_size": 25,
"sort_order": [
{
"order_by": "opportunity_id",
"sort_direction": "ascending"
}
]
}
}
OpenAI
We have spent a good amount of time in OpenAI and we can confirm that there are differences between our API body schema in OpenAPI format and what OpenAI expects to be input for the body schema on their end. For authentication please make sure that you are choosing Authentication Type: API Key and Auth Type Custom with a Customer header name of “X-Auth”. Failure to do so will cause OpenAI to fallback to a default of the Jwt auth which will fail.
Below is a list of the failures with the OpenAI file that is auto-generated from the API:
Could not find a valid URL in `servers`
Components section contains a circular dependency
In path /health, method get is missing operationId; skipping
In path /v1/agencies, method post is missing operationId; skipping
In path /v1/extracts, method post is missing operationId; skipping
In path /v1/opportunities/search, method post is missing operationId; skipping
In path /v1/opportunities/{opportunity_id}, method get is missing operationId; skipping
Found multiple security schemes, only 1 is supported
These issues can be fixed pretty easily manually:
- Could not find a valid URL in
servers - Found multiple security schemes, only 1 is supported
- In path /health, method get is missing operationId; skipping
- In path /v1/agencies, method post is missing operationId; skipping
- In path /v1/extracts, method post is missing operationId; skipping
- In path /v1/opportunities/search, method post is missing operationId; skipping
- In path /v1/opportunities/{opportunity_id}, method get is missing operationId; skipping
Not sure how hard the circular dependency would be to fix though.
We also have an extremely paired down openapi.yml file that can be used as a starting point
openapi: 3.1.0
info:
title: Simpler Grants API
description: Retrieve NIH grant announcements from the Simpler Grants API.
version: 1.0.0
servers:
- url: https://api.simpler.grants.gov
paths:
/v1/opportunities/search:
post:
operationId: getGrantAnnouncements
summary: Get NIH Grant Announcements
description: Search for NIH grant announcements using a provided query string. The search uses pre-defined filters for
the NIH (HHS-NIH11) agency, applicant types, close date, funding instrument, opportunity status, and post date
along with pagination settings.
security:
- apiKey: []
requestBody:
description: Payload for searching NIH grant announcements.
required: true
content:
application/json:
schema:
type: object
properties:
filters:
type: object
properties:
agency:
type: object
properties:
one_of:
type: array
items:
type: string
example:
- HHS-NIH11
applicant_type:
type: object
properties:
one_of:
type: array
items:
type: string
example:
- state_governments
- county_governments
close_date:
type: object
properties:
start_date:
type: string
format: date
example: 2025-05-07
funding_instrument:
type: object
properties:
one_of:
type: array
items:
type: string
example:
- cooperative_agreement
- grant
opportunity_status:
type: object
properties:
one_of:
type: array
items:
type: string
example:
- posted
post_date:
type: object
properties:
start_date:
type: string
format: date
example: 2023-01-01
required:
- agency
- applicant_type
- close_date
- funding_instrument
- opportunity_status
- post_date
pagination:
type: object
properties:
sort_order:
type: array
items:
type: object
properties:
order_by:
type: string
example: relevancy
sort_direction:
type: string
example: descending
required:
- order_by
- sort_direction
example:
- order_by: relevancy
sort_direction: descending
page_offset:
type: integer
example: 1
page_size:
type: integer
example: 20
sort_direction:
type: string
example: descending
required:
- sort_order
- page_offset
- page_size
- sort_direction
query:
type: string
description: The search term for NIH grant announcements.
example: cancer
required:
- filters
- pagination
- query
example:
filters:
agency:
one_of:
- HHS-NIH11
applicant_type:
one_of:
- state_governments
- county_governments
- individuals
- nonprofits_non_higher_education_with_501c3
- nonprofits_non_higher_education_without_501c3
- for_profit_organizations_other_than_small_businesses
- small_businesses
close_date:
start_date: 2025-05-07
funding_instrument:
one_of:
- cooperative_agreement
- grant
opportunity_status:
one_of:
- posted
post_date:
start_date: 2023-01-01
pagination:
page_offset: 1
page_size: 15
sort_order:
- order_by: relevancy
sort_direction: descending
query: cancer
responses:
"200":
description: Successful response with NIH grant announcements.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
additionalProperties: true
additionalProperties: true
default:
description: An error occurred.
components:
schemas: {}
securitySchemes:
apiKey:
type: apiKey
name: X-Auth
in: header
description: API key provided by Simpler Grants API.
Thank you for your patience as we learn along side you all. Hopefully these small fixes can help unblock folks that are having issues with API authentication. I do want to add as a small closing note that we will be implementing fixes to the documentation to make these things easier to understand for new users. However, we do not have plans at this time to provide schema for OpenAI’s API as we do not plan at this time to have built-in support for all GPT APIs. If anyone wants to create a working API call schema and share it out that would be great, but breaking changes will be coming to the API in the future that could make today’s work not work tomorrow.