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

# Riveterhq Riveter API

The Riveter API fills in new columns for rows of input data using AI, web searches, and web scrapes, so a list of companies can come back with their tech stack, pricing structure, or security tools. It also builds datasets of companies, people, or products from a natural-language prompt or a structured spec, scrapes a URL to plain text, runs a synchronous web search with structured results, and answers single research questions through its search agent. Asynchronous work returns a run that is checked, fetched, and stopped through one set of run endpoints, with optional webhook delivery when it finishes. Monitors re-run a saved enrichment daily, weekly, or monthly, and extractions turn a website into a reusable structured scraping recipe.

## For AI agents

Enrich rows of company or contact data with AI web research, build datasets from a prompt, scrape pages, run quick web searches, and poll or stop the resulting runs.

## Scope

Does not send outreach emails, store CRM records, or verify email deliverability. Use for AI web research, enrichment, dataset building, and scraping only.

## Capabilities

- Enrich rows of input data with new AI-researched columns through /enrich, using a saved enrichment_id or an inline prompt and attributes
- Build a dataset of companies, people, or products from a natural-language prompt, identifiers, and qualifiers
- Scrape a webpage to text synchronously, with an optional proxy_country_code
- Run a quick web search with an optional date_start and date_end and get structured results in one request
- Ask the search agent a single research question and get an answer shaped by an optional output_schema
- Check, fetch, and stop runs, with the wait parameter long-polling for results
- Schedule a monitor that re-runs an enrichment daily, weekly, or monthly and posts results to a webhook

## Use cases

### AI research agent that enriches account lists

An AI agent preparing sales research can hand a list of company names to Riveter instead of browsing each website itself. Through Jentic the agent searches for 'enrich a list of companies', loads the Riveter enrich operation with its input schema, and posts the rows with a prompt and the attributes it wants back, with the bearer key added at call time. It then long-polls the run result and returns the filled-in table.

Example prompt: POST /enrich with a list of 20 company domains in input and attributes for tech stack and pricing model, then call GET `/runs/{id}/result` with wait=30 until output is returned

### Prompt-built prospect datasets

Instead of buying a static list, a team describes the rows it wants, such as US fintech companies with a public API, and Riveter's dataset builder finds them. The request can combine a prompt with identifiers, qualifiers, attributes, and a max_items cap, and auto_run_enrichment can chain an enrichment over the new rows. A dataset can later be extended with more rows.

Example prompt: POST /datasets with the prompt 'fintech companies in the US with a public developer API' and max_items 50, then fetch the finished run with GET `/runs/{id}/result`

### Scheduled change monitoring

Some attributes change over time, such as a competitor's pricing or headcount. A Riveter monitor re-runs a saved enrichment over fixed input rows on a daily, weekly, or monthly cadence at a set hour and timezone, and can post results or only changes to a webhook. Listing a monitor's runs shows each scheduled execution and its status.

Example prompt: POST /monitors with an enrichment_id, cadence weekly, hour 9, minute 0, timezone Europe/Dublin, and a webhook_url for change alerts

### Quick search and page scraping for grounding

An agent answering a factual question often needs one search and one page read, not a full enrichment. Riveter's quick search returns structured results with URLs, titles, and snippets in the same response, and the scrape endpoint returns a page as text synchronously. The search agent covers scoped one-off questions such as a company's NAICS code.

Example prompt: POST /quick_search with a query about a company's latest funding round, then POST /scrape on the top result URL and summarise the page

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/enrich` | Enrich rows of input data |
| GET | `/runs/{id}/result` | Fetch a run's output |
| GET | `/runs/{id}` | Check run status |
| POST | `/datasets` | Build a dataset |
| POST | `/quick_search` | Run a quick web search |
| POST | `/scrape` | Scrape a webpage |
| POST | `/search_agent` | Ask a research question |
| POST | `/monitors` | Create a monitor |

## Key resources

- **Runs** — The shared record for every asynchronous job, with status values pending, enqueued, processing, success, and stopped
- **Enrichments** — Saved enrichment configurations that can be re-run by enrichment_id or turned into a dataset
- **Datasets** — Rows of companies, people, products, or URLs built from a prompt or structured spec
- **Monitors** — Schedules that re-run an enrichment on a daily, weekly, or monthly cadence
- **Extractions** — Reusable recipes for scraping structured records from a website

## 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:** 90 / 100
- **Maturity:** Agent-Optimized
- **Dimensions:**
  - Foundational Compliance: 73 / 100
  - Developer Experience & Jentic Compatibility: 100 / 100
  - AI-Readiness & Agent Experience: 100 / 100
  - Agent Usability: 94 / 100
  - Security: 100 / 100
  - AI Discoverability: 74 / 100
- **View full report:** https://jentic.com/apis/riveterhq.com/riveterhq/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 Riveter by hand means sending a bearer key, choosing between inline configs and saved enrichment ids, and handling the run lifecycle with long-polling or webhooks. Through Jentic you install once, import Riveter from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Riveter carries the rows, enrichment_id, and prompt inside the request body of calls like /enrich, so rules bound which operations your agent may call, not which enrichment it runs. You choose the operations it may call, so credit-spending ones like /enrich, /datasets, or creating monitors are not included unless you add them.
- **Credential handling:** Your Riveter API 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 'enrich a list of companies' or 'scrape a webpage', and Jentic returns the matching Riveter operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Clay Public API** — Table-based enrichment that combines data providers and AI research for go-to-market lists
- **Firecrawl API** — Crawl and scrape websites into clean markdown or structured data
- **Exa** — Neural web search that returns pages and content for AI applications
- **People Data Labs API** — Structured person and company records from a large licensed dataset

## FAQ

### What authentication does the Riveter API use?

Per its OpenAPI spec, the Riveter API uses HTTP bearer authentication: send your API key as `Authorization: Bearer YOUR_API_KEY` on each request. Through Jentic the key is held by your own instance and injected at call time, so the agent never sees it.

### Can I get enrichment results without polling with the Riveter API?

Yes. Pass webhook_url in the body when you start a run with /enrich and Riveter posts the results to your URL when the run finishes; dataset builds take dataset_webhook_url. If you poll instead, GET `/runs/{id}/result` accepts a wait parameter that long-polls for the output.

### What are the rate limits for the Riveter API?

The Riveter OpenAPI spec states a default of 30 requests per minute per endpoint group, with `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers on responses. It also caps rows per /enrich request: up to 10,000 with an enrichment_id, and 1,000 with an inline configuration.

### Is there a Riveter MCP server?

Yes - Riveter offers an official MCP server. You can also connect the Riveter API directly through Jentic: your agent gets the full 27-endpoint surface without loading another server's tool definitions into its context, your API key is injected at call time by your self-hosted instance instead of living in an MCP config, and your rules decide which operations the agent may call.

### How do I enrich a list of companies through Jentic?

Search Jentic for 'enrich a list of companies', load the POST /enrich operation, and execute it with your rows in input plus a prompt and attributes, or an existing enrichment_id. Then load GET `/runs/{id}/result` to fetch the output. To run it on your own infrastructure, install Jentic One from its GitHub repo.

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

Yes. For a research agent, write a rule that allows only POST /quick_search, POST /scrape, and GET `/runs/{id}/result`, so it can search, read pages, and fetch results but cannot start paid enrichments, create monitors, or edit saved enrichments. Every call it makes is logged.

### Can I estimate what a Riveter request will cost before running it?

Yes. The kickoff requests in the spec, including /enrich, /datasets, /quick_search, /search_agent, and /scrape, accept an estimate_cost flag and a max_credits ceiling, so an agent can check the cost first and cap how many credits a run may use.
