canonical: https://jentic.com/apis/formulasignal.com/formulasignal

# FormulaSignal Intelligence API

The FormulaSignal Intelligence API answers bounded questions about U.S. pre-workout supplement products, drawing on a dated, evidence-backed Record of what products declare, what they cost per serving, and how those facts have changed. It resolves a brand or product name to a canonical product, returns a product's current record and classified historical timeline, compares products, and explains reviewed change Signals with their citations. Research and regulatory context endpoints return ingredient dose ranges and documented cautions, and a watchlist tracks monitoring state for a bound account.

## For AI agents

Answer bounded questions about U.S. pre-workout supplement products: resolve a product, read its current record and history, compare products, and explain reviewed change Signals with citations. Retrieve ingredient dose ranges, regulatory cautions, and the published Category Ledger.

## Scope

Does not export the full Record, list all products, or return source documents. Use for bounded, citation-backed answers about covered U.S. pre-workout products only.

## Capabilities

- Answer one bounded question from the covered pre-workout Record
- Resolve a brand, product name, or alias to one canonical covered product
- Return a product's current record and its classified historical timeline
- Compare two or three covered products on consistent criteria
- Explain a reviewed change Signal between two comparable product states, with citations
- Return ingredient dose ranges and documented regulatory cautions for named ingredients
- Track a bound account's watchlist and read its monitoring receipt

## Use cases

### Agent Product Research

An AI agent connected through Jentic can resolve a pre-workout product by name, read its current record, and compare it against another product without a developer wiring the FormulaSignal API by hand. The agent searches by intent and receives bounded, citation-backed answers rather than raw data to re-interpret.

Example prompt: Resolve two pre-workout product names and compare them on consistent criteria, returning the differences

### Change Monitoring

Analysts track when a product's declared formula or price changes. FormulaSignal returns approved Signals in release order for incremental polling and explains each confirmed change between two comparable product states, with the citation behind it.

Example prompt: Poll for new Signals since the last check and explain the most recent confirmed change

### Ingredient and Regulatory Context

Researchers need the dose range used for an ingredient in the evidence set and the documented regulatory records for it. FormulaSignal returns research and regulatory context for named ingredients, each result carrying the class of record it actually is.

Example prompt: Return the dose range and regulatory cautions for a named ingredient with their citations

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/record/search` | Answer a bounded question from the Record |
| POST | `/api/v1/products/resolve` | Resolve a name or alias to a canonical product |
| GET | `/api/v1/products/{product_id}` | Get a product's current record |
| GET | `/api/v1/products/{product_id}/history` | Get a product's historical timeline |
| POST | `/api/v1/products/compare` | Compare two or three covered products |
| GET | `/api/v1/signals` | List approved Signals, newest first |
| POST | `/api/v1/regulatory/context` | Return regulatory context for named ingredients |

## Key resources

- **Record and products** — Search the Record, resolve a product, and read a product's current record, history, and serving economics
- **Signals** — List approved Signals in release order and explain one reviewed change
- **Comparisons** — Compare two or three covered products on consistent criteria
- **Context** — Return research dose ranges and regulatory cautions for named ingredients
- **Category Ledger** — List published Category Ledger editions and return one edition
- **Watchlist** — Read, add to, and remove from the bound account's watchlist and read its receipt

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 67 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 80 / 100
  - Developer Experience & Jentic Compatibility: 69 / 100
  - AI-Readiness & Agent Experience: 49 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 74 / 100
- **View full report:** https://jentic.com/apis/formulasignal.com/formulasignal/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the FormulaSignal Intelligence API by hand means handling its environment-prefixed bearer key, learning which route is public, and shaping each bounded question yourself. Through Jentic you install once, import FormulaSignal from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** FormulaSignal exposes read and search operations alongside a small watchlist that can be modified, so a rule can let your agent resolve, read, and compare products while leaving the watchlist writes out. You choose the operations it may call, so changes like adding to or removing from the watchlist are not included unless you add them.
- **Credential handling:** Your FormulaSignal key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'resolve a pre-workout product' or 'compare two products', and Jentic returns the matching FormulaSignal operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Firecrawl** — Web crawling and extraction API for gathering product data from pages yourself.
- **NewsAPI** — News search API for tracking brand and product coverage.
- **Mediastack** — Live and historical news data feed by keyword and source.

## FAQ

### What authentication does the FormulaSignal Intelligence API use?

The FormulaSignal Intelligence API authenticates with a bearer token sent in the Authorization header, per its OpenAPI spec; the key is environment-prefixed and an `X-FormulaSignal-Key` header is accepted as an alternative. The key is never read from a query string, so it cannot reach an access log. The health check is the only route that needs no key. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time.

### Can I compare two pre-workout products with the FormulaSignal Intelligence API?

Yes. The compare operation evaluates two or three covered products on consistent FormulaSignal criteria in a single bounded call and returns the differences with the context behind them.

### Can I limit what my agent is allowed to do with the FormulaSignal Intelligence API?

Yes. Write a rule that allows only the read and search operations, such as resolving products, reading records, and comparing them, so the agent cannot change the account watchlist. Every call it makes is logged.

### Is there a FormulaSignal MCP server?

You do not need an MCP server to give your agent the FormulaSignal Intelligence API. Jentic connects it directly from the API Directory: import FormulaSignal, store your key once, and the agent calls its operations by intent without loading another server's tool definitions into its context.

### What are the rate limits for the FormulaSignal Intelligence API?

The OpenAPI spec does not specify numeric rate limits for the FormulaSignal Intelligence API. Check the FormulaSignal documentation at https://formulasignal.com/developers/keys for current limits.

### How do I look up a pre-workout product with the FormulaSignal Intelligence API through Jentic?

Search Jentic for an intent like 'resolve a pre-workout product', and it returns FormulaSignal's resolve and record operations with their input schemas so your agent can turn a product name into a canonical record. To run it on your own infrastructure, install Jentic One from its GitHub repo.