API

Developers

A read-only API over the RPF catalogue. Versioned, licensed, and metered in rows rather than requests.

Open the OpenAPI documentAsk for a key
The API specification and this guide are currently available in English.

What you get

46 published read endpoints, described in the OpenAPI 3.1 document. It is regenerated per request from the same schemas the handlers validate against, so it cannot describe a shape the code does not implement.

Anonymous callers get the whole reading surface. Lists return a teaser projection and are paginated; single-item detail returns full rows to everyone, so citing one thing never needs a key.

Version 1.0.0 is stable.
Documented response shapes will not change incompatibly within v1. Additive change is not breaking: new properties may appear on any response, so ignore unknown properties. A breaking change means a new major version and a new vendor media type; v1 keeps answering. If an endpoint is ever withdrawn it is announced first, marked `deprecated` in this document, and served for at least six months after that mark appears. Pin the major version by sending Accept: application/vnd.rpf.v1+json.

Three recipes

  1. 1. Walk the action statements

    Page through the catalogue with a keyset cursor.

    Shell
    curl -s "https://rpf.bimexcellence.org/api/action-statements?limit=50" \
  -H "Accept: application/vnd.rpf.v1+json"

# then, for each page:
curl -s "https://rpf.bimexcellence.org/api/action-statements?limit=50&cursor=<meta.nextCursor>"

    meta.nextCursor being null is the only end-of-list signal. Do not stop on a short page, and do not build your own offset: a malformed cursor is a 400 rather than a silent reset to page one.

  2. 2. Read one statement in one language

    Flatten the multilingual bundles to a single locale.

    Shell
    curl -s "https://rpf.bimexcellence.org/api/action-statements/<id>?locale=es"

    Omit ?locale= and you receive the full LangText bundle instead, which carries en plus whichever of pt-BR, fr and es have been translated. en is always present and is the fallback for the rest.

  3. 3. Call it from a browser

    No proxy needed for the statement, package and specification endpoints.

    JavaScript
    // 20 of the 46 published endpoints answer cross-origin.
const res = await fetch(
  "https://rpf.bimexcellence.org/api/action-statements?limit=10",
);
const { data, meta } = await res.json();

// The notice headers are exposed to browser callers too:
res.headers.get("x-rpf-api-stability"); // "stable"
res.headers.get("link");                // the licence

    Cross-origin requests never carry credentials, so a browser will not attach a session. An API key header is accepted, because it is a token you hold deliberately. The statements, packages, spec families answer cross-origin; the catalogue lists, registers, search and metro map do not.

Limits, and how to raise them

Anonymous reads are metered per identity per UTC day, counted in rows served rather than requests. That is deliberate: it makes the response format irrelevant, so a CSV export costs exactly what the same rows cost as JSON, and no format can become the cheap way round a page limit.

A key raises the row budget, not just the request ceiling. Send it as x-rpf-api-key: rpf_… or Authorization: Bearer rpf_…. An invalid or revoked key is not an error: it falls back to anonymous treatment, so a stale credential degrades to the public allowance rather than becoming an outage.

Keys are issued by hand today. Email support@bimexcellence.org with what you are building and roughly what volume you need.

Licence

The catalogue is licensed CC-BY-NC-SA-4.0. Attribution required, non-commercial, share-alike. Every response carries it as a Link: rel="license" header, and package payloads embed it, because a file saved to disk arrives without its headers. See the licence page for what commercial use needs.

Where to go next