Build on HostRepute
HostRepute’s REST API is a blacklist monitoring API for your own scripts and tools: it adds and removes the domains and IPs your team monitors, runs one-off blocklist, certificate and email authentication checks, and manages alert channels and delivery hours. Around it, HostRepute offers webhooks, an MCP server for AI clients, Prometheus metrics and an API for private certificate agents. This page explains what each one is for and where to start.
How the API works
Section titled “How the API works”- Base URL. Every endpoint is under
https://app.hostrepute.com/api/v1. - Authentication. Each request carries a team API token as
Authorization: Bearer <token>. A token belongs to one team and can do only what its abilities allow. Members with the Developer role or higher create tokens in Settings, then API tokens. Read authentication and API tokens. - JSON in and out. Send request bodies as JSON with
Content-Type: application/json. Responses are JSON, errors included, with two exceptions: the Prometheus metrics are plain text, and a delete answers204with no body. Read errors. - Lists come in pages of 15 items by default and 100 at most. Read pagination.
- Rate limit. A team’s tokens share 120 requests per minute. Read rate limits.
- Checks use credits. A blocklist, certificate or email authentication check you start through the API costs 1 credit, like a manual one in the portal. Monitoring the domains and IPs you add stays part of the plan. Read run checks and wait for results.
- Internal names. Paths and fields use HostRepute’s internal words, not the portal’s labels:
hostsare domains and IPs,data-sourcesblocklists,data-source-groupscheck profiles,alertsalert channels,alert-groupsdelivery hours,deliverabilityemail authentication, andblacklistblocklist checks.
The API is part of every plan and the trial.
What the API covers
Section titled “What the API covers”The API reference describes every endpoint, grouped as in this table.
| Area | Paths under /api/v1 |
What you can do |
|---|---|---|
| Domains and IPs | /hosts |
List, add, read, update and delete the domains and IPs your team monitors. |
| Check profiles | /data-source-groups |
List, create, read, update and delete check profiles. |
| Blocklists | /data-sources |
List and read the blocklists HostRepute can check. |
| Blocklist scans | /blacklist/check, /blacklist/status/{uuid} |
Check any domain or IP against a check profile’s blocklists, then read the result. |
| Certificate checks | /certificates/check, /certificates/status/{uuid} |
Check a TLS certificate on any host and port, then read the result and grade. |
| Email authentication checks | /deliverability/check, /deliverability/status/{uuid} |
Check a domain’s or IP’s reverse DNS, MX, SPF, DMARC, MTA-STS, TLS-RPT and BIMI records. The answer holds the result. |
| Alert channels | /alerts, /alerts/{uuid}/test |
List, add, read, update and delete alert channels, and send a test alert. |
| Delivery hours | /alert-groups |
List, add, read, update and delete delivery hours. |
| Metrics | /metrics |
Read your team’s totals in the Prometheus text format. |
| Certificate agent | /certificate-agent/tasks |
For private agents only: fetch the certificate checks that are due and post their results. |
Blocklist and certificate checks run in the background: you start one, then poll its status or give a callback_url
that HostRepute calls when the check ends. An email authentication check runs while you wait.
The API doesn’t cover uptime, domain expiry, inbox providers (Google Postmaster Tools, Microsoft SNDS, Yahoo Sender Hub
and ESP connections), delisting requests, campaign preflights, scheduled reports, status pages, shared reports, members
or billing. Use the portal for those, or read several of them through the MCP server. The REST API has no credit
balance endpoint either: the balance shows only in a 402 answer and in the answer to an email authentication check.
Other ways to connect
Section titled “Other ways to connect”Webhooks
Section titled “Webhooks”HostRepute sends two kinds of signed POST requests to your servers:
- a scan callback when a blocklist or certificate check you started through the API ends, to the
callback_urlyou gave; - an alert from the webhook alert channel whenever that channel is alerted, for example when a domain is listed or an uptime check goes down.
Read receive webhooks for the headers, the signatures and how to verify them, and webhook events for every event.
MCP server for AI clients
Section titled “MCP server for AI clients”The MCP (Model Context Protocol) server at https://app.hostrepute.com/mcp/hostrepute lets an AI client such as an
assistant in your editor read your teams and start checks. It reads more than the REST API, including uptime monitors,
delisting requests, status pages, scheduled reports and inbox providers, for every team you belong to. It signs in as
you, not as a team: it uses OAuth or an MCP token from Settings, then AI clients (MCP), never a
team API token, and allows 60 requests per minute per person. Read connect AI clients with MCP
and the list of MCP tools, resources and prompts.
Prometheus metrics
Section titled “Prometheus metrics”GET /api/v1/metrics returns your team’s totals, such as how many domains and IPs are listed and how many certificates
are unhealthy, as Prometheus gauges, for a dashboard or alerting rules in your own monitoring. It needs a token with
metrics:read. Read scrape Prometheus metrics.
Private certificate agents
Section titled “Private certificate agents”A private agent is a program you run inside your network to check certificates the internet can’t reach. It uses the
two /api/v1/certificate-agent endpoints with its own hrca_ token, not a team API token. Read
check internal certificates with a private agent.
HostRepute is preparing client libraries for Go, Node.js, Python, PHP and Ruby. None of them is published yet, so use the REST API directly for now. Read official SDKs.
OpenAPI file and Postman collection
Section titled “OpenAPI file and Postman collection”The API reference is built from an OpenAPI 3.0 description that you can use in your own tools, for example to generate a client or to load the API into an HTTP client:
- OpenAPI:
https://docs.hostrepute.com/openapi.yaml - Postman collection:
https://docs.hostrepute.com/collection.json
Both use https://app.hostrepute.com as the server; the Postman collection holds it in the baseUrl variable. The
collection is set up for bearer authentication with an empty token: add your team API token to the collection’s
authorization settings before you send a request.
Which one to use
Section titled “Which one to use”| You want to | Use |
|---|---|
| Add the domains and IPs you create elsewhere, such as a new sending domain | The API: add a domain or IP |
| Check an IP or domain for listings before you start sending from it | The API: a blocklist check |
| Get told in your own system when a domain or IP is listed or removed | The webhook alert channel |
| Show HostRepute numbers on a dashboard you already run | Prometheus metrics |
| Ask an AI assistant about your reputation, or let it start checks | The MCP server |
| Watch certificates on servers inside your network | A private agent |