Search engine integrations

API docs.

Resolve a search query into one eligible text ad, then link through its click URL.

Quick start

Ask a SUPER_ADMIN for a named integration key from the API keys tab. Set it as KEYWORD_MARKET_API_KEY on your server and send it in the X-API-Key header. Keep the key out of browsers, URLs and logs.

curl --get 'https://precommunity.org/api/v1/keyword-market/resolve' \
  --data-urlencode 'q=bitcoin' \
  --header "X-API-Key: $KEYWORD_MARKET_API_KEY"

This example uses the production origin. For another environment, replace the origin and keep /api/v1/keyword-market. The q parameter is required: up to 256 characters and 32 word tokens.

Each key allows up to 60 requests in a one-second window. The window starts with its first request, and the allowance resets when it ends. On 429, wait for the number of seconds in Retry-After before retrying.

Use the response

A successful request returns ad with only the fields needed to display it.

{
  "ad": {
    "headline": "Explore Bitcoin",
    "description": "Learn more about Bitcoin.",
    "clickUrl": "https://precommunity.org/api/v1/keyword-market/revisions/00000000-0000-4000-8000-000000000001/click?delivery=<signed-token>",
    "url": "https://example.com/bitcoin",
    "reportUrl": "https://precommunity.org/keyword-market/reports/00000000-0000-4000-8000-000000000001"
  }
}

Render headline and description, and use clickUrl exactly as returned, including its query parameters, as the link. It records the click and redirects to url, the full HTTPS destination address. Request a new resolver response for each ad delivery so each viewer receives their own click link.

Each click link can create a charge for one hour. Expired links still redirect. Only one click per campaign and client IP is billable in a rolling 5-minute window; other clicks still redirect. The USD bid and PRE conversion rate are fixed at the first accepted billable click.

Use reportUrl for a Report ad link. It opens a public form on Precommunity; no login is required. Opening the link does not save a report. The user selects a reason, can add a comment of up to 500 characters, then submits it for Moderation.

If the response is { "ad": null }, show no ad. This can also happen while the market is syncing.

Matching uses whole words, prefers the longest eligible phrase, then the highest USD bid. Each regular GET delivery containing an ad counts as a View. Responses are no-store; do not cache them in your integration.

Endpoints

Base URL: https://precommunity.org/api/v1/keyword-market

GET /resolve?q=bitcoin: One matching ad or null. Requires X-API-Key.
GET /revisions/:revisionId/click: 302 redirect. Use the returned clickUrl. No key.
POST /revisions/:revisionId/reports: Anonymous report submission from the reportUrl form. Rate limited; returns 202.
GET /keywords/:keyword: Public stake ranking for an exact keyword. No key; does not count Views.
GET /status: Chain and indexer readiness. No key.

Errors

400 — Missing or invalid query.
401 — Missing, invalid or revoked API key.
404 — Market disabled or click revision unavailable.
429 — Request limit reached; retry after the Retry-After delay.
503 — Service temporarily unavailable; retry later.