{"openapi":"3.1.0","info":{"title":"Candid (BYOK) API","version":"0.1.0","description":"Candid (BYOK) lets an AI assistant read your own Candid data through the Candid API with a key you supply (Candid API subscription key). Read-only: 12 tools (check_charity, check_charity_california, get_nonprofit_profile, get_nonprofit_financials, search_nonprofits, search_nonprofits_by_state, list_search_filters, list_filter_values, get_grants_summary, search_grant_funders,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-candid.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-candid/docs"},"termsOfService":"https://connectorbay.com/byok-candid/terms"},"servers":[{"url":"https://byok-candid.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-candid/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/check_charity":{"post":{"operationId":"check_charity","summary":"Run the IRS charity check for a US nonprofit by EIN: legal name, location, IRS Publication 78 and business master file s","description":"Run the IRS charity check for a US nonprofit by EIN: legal name, location, IRS Publication 78 and business master file status, subsection, foundation type, ruling year, OFAC and revocation flags. Use for \"Is EIN 13-1837418 a valid, IRS-eligible charity\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ein":{"description":"Employer Identification Number of the US nonprofit, written with the dash, for example '13-1837418'.","maxLength":20,"title":"Ein","type":"string"}},"required":["ein"],"title":"check_charityArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/check_charity_california":{"post":{"operationId":"check_charity_california","summary":"Run the charity check with the California Attorney General registry status added for a nonprofit by EIN. Use for \"Is EIN","description":"Run the charity check with the California Attorney General registry status added for a nonprofit by EIN. Use for \"Is EIN 13-1837418 in good standing in California\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"const":"ca","description":"State code for the state-level check; only 'ca' (California) is documented.","title":"State","type":"string"},"ein":{"description":"Employer Identification Number of the US nonprofit, written with the dash, for example '13-1837418'.","maxLength":20,"title":"Ein","type":"string"}},"required":["state","ein"],"title":"check_charity_californiaArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_nonprofit_profile":{"post":{"operationId":"get_nonprofit_profile","summary":"Get a nonprofit's Candid profile by EIN: name, address, mission, website, founding and ruling years, NTEE code, tax-dedu","description":"Get a nonprofit's Candid profile by EIN: name, address, mission, website, founding and ruling years, NTEE code, tax-deductibility, staff and volunteer counts. Use for \"What is the mission and size of the nonprofit with EIN 13-1837418\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ein":{"description":"Employer Identification Number of the US nonprofit, written with the dash, for example '13-1837418'.","maxLength":20,"title":"Ein","type":"string"}},"required":["ein"],"title":"get_nonprofit_profileArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_nonprofit_financials":{"post":{"operationId":"get_nonprofit_financials","summary":"Get the most recent annual financials of a nonprofit by EIN (revenue, expenses, assets and related figures) from its Can","description":"Get the most recent annual financials of a nonprofit by EIN (revenue, expenses, assets and related figures) from its Candid profile. Use for \"What were the latest revenue and expenses of EIN 13-1837418\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ein":{"description":"Employer Identification Number of the US nonprofit, written with the dash, for example '13-1837418'.","maxLength":20,"title":"Ein","type":"string"}},"required":["ein"],"title":"get_nonprofit_financialsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_nonprofits":{"post":{"operationId":"search_nonprofits","summary":"Search Candid's Essentials index of US nonprofits by keywords. Returns name, EIN, mission, website, profile level, city ","description":"Search Candid's Essentials index of US nonprofits by keywords. Returns name, EIN, mission, website, profile level, city and state of each match, with paging. Use for \"Find nonprofits working on reforestation\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_terms":{"description":"Keywords to search for, for example 'reforestation'.","maxLength":200,"title":"Search Terms","type":"string"},"offset":{"anyOf":[{"maximum":9900,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip, for paging (0 for the first page).","title":"Offset"},"size":{"anyOf":[{"maximum":25,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many nonprofits to return (1 to 25).","title":"Size"}},"required":["search_terms"],"title":"search_nonprofitsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_nonprofits_by_state":{"post":{"operationId":"search_nonprofits_by_state","summary":"Search Candid's Essentials index of US nonprofits within one state, optionally with keywords. Use for \"List climate nonp","description":"Search Candid's Essentials index of US nonprofits within one state, optionally with keywords. Use for \"List climate nonprofits in Colorado\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"description":"Two-letter US state code, for example 'CO'.","maxLength":2,"title":"State","type":"string"},"search_terms":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional keywords, for example 'climate'.","title":"Search Terms"},"offset":{"anyOf":[{"maximum":9900,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip, for paging (0 for the first page).","title":"Offset"},"size":{"anyOf":[{"maximum":25,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many nonprofits to return (1 to 25).","title":"Size"}},"required":["state"],"title":"search_nonprofits_by_stateArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_search_filters":{"post":{"operationId":"list_search_filters","summary":"List the lookup tables (filter names) that can be used to build Essentials searches, such as subject, population and NTE","description":"List the lookup tables (filter names) that can be used to build Essentials searches, such as subject, population and NTEE codes. Use for \"Which filters can I use to search Candid nonprofits\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_search_filtersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_filter_values":{"post":{"operationId":"list_filter_values","summary":"List the values of one Essentials lookup table with their keys and search values, for example all subject codes. Use for","description":"List the values of one Essentials lookup table with their keys and search values, for example all subject codes. Use for \"What subject codes can I filter nonprofits by\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter_name":{"description":"Name of the lookup table, taken from list_search_filters, for example 'subjects'.","maxLength":60,"title":"Filter Name","type":"string"}},"required":["filter_name"],"title":"list_filter_valuesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_grants_summary":{"post":{"operationId":"get_grants_summary","summary":"Summarize grants matching a keyword, place, year or minimum amount: number of grants, total value, number of foundations","description":"Summarize grants matching a keyword, place, year or minimum amount: number of grants, total value, number of foundations and recipients. Use for \"How much grant money went to water projects in 2022\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Keyword to search for, for example 'clean energy'.","title":"Query"},"location":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"GeoNames id of the place to search in, for example 6252001 for the United States.","title":"Location"},"geo_id_type":{"anyOf":[{"const":"geonameid","type":"string"},{"type":"null"}],"default":null,"description":"Type of the location id; only geonameid is supported. Send it together with location.","title":"Geo Id Type"},"location_type":{"anyOf":[{"enum":["funder","recipient","area_served"],"type":"string"},{"type":"null"}],"default":null,"description":"What the location refers to: the funder, the recipient or the area served.","title":"Location Type"},"year":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Award year or several years separated by commas, for example '2022' or '2021,2022'.","title":"Year"},"min_amt":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only grants of at least this many US dollars.","title":"Min Amt"},"include_gov":{"anyOf":[{"enum":["yes","no"],"type":"string"},{"type":"null"}],"default":null,"description":"Whether US government grantmakers are included: yes or no.","title":"Include Gov"}},"title":"get_grants_summaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_grant_funders":{"post":{"operationId":"search_grant_funders","summary":"Search funders by grant activity (keyword, place, year, minimum amount). Returns funder name, location, EIN, total amoun","description":"Search funders by grant activity (keyword, place, year, minimum amount). Returns funder name, location, EIN, total amount and number of grants; 25 per page. Use for \"Which funders gave the most to clean energy grants\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Keyword to search for, for example 'clean energy'.","title":"Query"},"location":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"GeoNames id of the place to search in, for example 6252001 for the United States.","title":"Location"},"geo_id_type":{"anyOf":[{"const":"geonameid","type":"string"},{"type":"null"}],"default":null,"description":"Type of the location id; only geonameid is supported. Send it together with location.","title":"Geo Id Type"},"location_type":{"anyOf":[{"enum":["funder","recipient","area_served"],"type":"string"},{"type":"null"}],"default":null,"description":"What the location refers to: the funder, the recipient or the area served.","title":"Location Type"},"year":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Award year or several years separated by commas, for example '2022' or '2021,2022'.","title":"Year"},"min_amt":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only grants of at least this many US dollars.","title":"Min Amt"},"include_gov":{"anyOf":[{"enum":["yes","no"],"type":"string"},{"type":"null"}],"default":null,"description":"Whether US government grantmakers are included: yes or no.","title":"Include Gov"},"sort_by":{"anyOf":[{"enum":["funder_name","funder_city","funder_state","funder_country","amount","count"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by funder_name, funder_city, funder_state, funder_country, amount or count.","title":"Sort By"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Sort Order"},"page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number of results, starting at 1 (maximum 100); each page holds up to 25 rows.","title":"Page"}},"title":"search_grant_fundersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_grant_recipients":{"post":{"operationId":"search_grant_recipients","summary":"Search grant recipients by keyword, place, year or minimum amount. Returns recipient name, location, EIN, total amount r","description":"Search grant recipients by keyword, place, year or minimum amount. Returns recipient name, location, EIN, total amount received and number of grants; 25 per page. Use for \"Which organizations received the most grants for solar projects\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Keyword to search for, for example 'clean energy'.","title":"Query"},"location":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"GeoNames id of the place to search in, for example 6252001 for the United States.","title":"Location"},"geo_id_type":{"anyOf":[{"const":"geonameid","type":"string"},{"type":"null"}],"default":null,"description":"Type of the location id; only geonameid is supported. Send it together with location.","title":"Geo Id Type"},"location_type":{"anyOf":[{"enum":["funder","recipient","area_served"],"type":"string"},{"type":"null"}],"default":null,"description":"What the location refers to: the funder, the recipient or the area served.","title":"Location Type"},"year":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Award year or several years separated by commas, for example '2022' or '2021,2022'.","title":"Year"},"min_amt":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only grants of at least this many US dollars.","title":"Min Amt"},"include_gov":{"anyOf":[{"enum":["yes","no"],"type":"string"},{"type":"null"}],"default":null,"description":"Whether US government grantmakers are included: yes or no.","title":"Include Gov"},"sort_by":{"anyOf":[{"enum":["recip_name","recip_city","recip_state","recip_country","amount","count"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by recip_name, recip_city, recip_state, recip_country, amount or count.","title":"Sort By"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Sort Order"},"page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number of results, starting at 1 (maximum 100); each page holds up to 25 rows.","title":"Page"}},"title":"search_grant_recipientsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_sector_news":{"post":{"operationId":"search_sector_news","summary":"Search Candid's curated news on nonprofits and philanthropy by keywords and dates. Returns title, publication date, sour","description":"Search Candid's curated news on nonprofits and philanthropy by keywords and dates. Returns title, publication date, source and link of each article. Use for \"What philanthropy news mentions tree planting this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_terms":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"default":null,"description":"Keywords to look for, for example 'tree planting' (up to 255 characters).","title":"Search Terms"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles published on or after this date, YYYY-MM-DD.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles published on or before this date, YYYY-MM-DD.","title":"End Date"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by publication date: desc (newest first) or asc.","title":"Sort Order"},"page":{"anyOf":[{"maximum":400,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (maximum 400).","title":"Page"}},"title":"search_sector_newsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}