Rovas exposes a REST API so partners, plugins, and apps can create accounts, file work reports, read Merits, and plug into NeoFund products such as Civic.

Environment Base URL
Production https://rovas.app
Development https://dev.rovas.app

Service paths use the prefix /rovas. OAuth protocol paths use /oauth2.

Send Accept: application/json and, for POST/PUT bodies, Content-Type: application/json.

If you are planning an integration, contact us — we can provision partner access and review your use case.

Solutions built with the API

Apps and plugins that integrate third-party tools with Rovas are listed on the Rovas connectors page.

Which API should I use?

Model How you authenticate Best for
Classic HTTP headers API-KEY and TOKEN Partner backends, website plugins, server-to-server jobs
OAuth 2 (Bearer) Authorization: Bearer <access_token> Mobile / SPA clients with browser login (e.g. Civic)

Do not mix both on one request. Classic endpoints expect API keys; Civic-oriented endpoints have API-key auth disabled and expect Bearer (or are public).

Auth labels in this reference

Label Meaning
API-KEY Headers API-KEY + TOKEN (classic)
Bearer Authorization: Bearer with scope user_profile
Public No credentials (API-key auth disabled on the resource)
Optional Bearer Public read; Bearer adds user-specific fields

Classic API — how to use it

Credentials

  1. Sign in to Rovas and open My account → Rovas API.
  2. Copy the API key and Token.
  3. On each authenticated call, send:
API-KEY: <your api key>
TOKEN: <your token>

Each key pair belongs to one Rovas user. Calls run as that user.

Charities and other partners that create Rovas accounts for donors or members need a technical account with the api client role (assigned by NeoFund/Rovas admins). That account’s API key is used only for account provisioning.

Preferred endpoint

POST /rovas/rovas_partner_user

Legacy equivalent: POST /rovas/rules/rules_create_user (same body and response).

Request body (required fields)

Field Description
user_name Display name
user_id Your external numeric user id
user_email Email (used to find an existing Rovas account)
user_country ISO 3166-1 alpha-2, uppercase (e.g. SK)
user_language Language code (e.g. sk, en)
server_url Your site base URL (e.g. https://partner.example/)

Optional: hybridauth_provider (defaults to Nabezky if empty), partner_client_id.

List allowed providers: GET /rovas/rovas_hybridauth_providers.json (usually public).

Success response

{
  "rovas_uid": 123,
  "api_key": "…",
  "token": "…"
}

Store the returned api_key / token and use them as API-KEY / TOKEN for later calls on behalf of that end user.

Example

curl -sS -X POST "https://rovas.app/rovas/rovas_partner_user" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $PARTNER_API_KEY" \
  -H "TOKEN: $PARTNER_TOKEN" \
  -d '{
    "user_name": "Jane Partner User",
    "user_id": 12345,
    "user_email": "jane@example.com",
    "user_country": "SK",
    "user_language": "en",
    "server_url": "https://partner.example/",
    "hybridauth_provider": "Nabezky"
  }'

Typical errors: 400 validation, 401 bad credentials, 403 missing api client permission.

Work reports (classic)

POST /rovas/rules/rules_proxy_create_work_report accepts optional reward_kind (merits | chrons, default chrons) so third-party apps can request Merits after approval — same preference store as Civic OAuth. On same-day merges into one work report, merits is sticky.

Optional deferred app fee: usage_fee_project_id + usage_fee_rate (both or neither). On approval, Rovas charges that fee from work-report Chron proceeds, then (when reward_kind=merits) converts grant − Rovas 1% − app fee to Merits. Prefer this over a separate rules_proxy_create_aur call when electing Merits. Full request schema is in the OpenAPI reference below.


OAuth 2 / Bearer — how to use it

OAuth is used by NeoFund’s Civic app and by other clients we register. New products need their own OAuth client — do not reuse Civic’s client_id from a third-party app.

Protocol endpoints

Method Path Auth Notes
GET /oauth2/authorize browser session PKCE; Civic supports lang, intent
POST /oauth2/token public client + PKCE authorization_code / refresh_token
POST /oauth2/revoke token Revoke access/refresh
GET /oauth2/tokens/{access_token} — Introspect → user_id, client_id, expires, scope (404 if invalid)

Civic client (reference)

Setting Value
client_id civic
Client type Public (no secret)
Grants Authorization code + refresh token
PKCE Required (S256)
Scope user_profile
Redirect civic://oauth/callback

Authorize query extras: lang=sk|en, intent=login|register.

Token exchange (authorization code + PKCE)

curl -sS -X POST "https://rovas.app/oauth2/token" \
  -d grant_type=authorization_code \
  -d client_id=civic \
  -d redirect_uri=civic://oauth/callback \
  -d code=PASTE_CODE \
  -d code_verifier=$VERIFIER

Call an API with Bearer

curl -sS "https://rovas.app/rovas/me" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Example GET /rovas/me response:

{
  "uid": 42,
  "username": "sano",
  "display_name": "Alexander Žaťko",
  "total_me": 1248.35,
  "total_chr": 320.0,
  "created": "2019-03-12T14:22:01+00:00",
  "language": "sk",
  "receipt_history_retention": null
}

Support

Questions or a new OAuth client: contact NeoFund.

Full endpoint reference (from OpenAPI) follows below.

Endpoint reference

OpenAPI version: 1.1.0Download OpenAPI (YAML)

Operation summaries, descriptions, and schemas below are in English (from the OpenAPI source).

Classic API endpoints

Classic API — accounts and identity (API-KEY + TOKEN)

POST/rovas/rules/rules_create_userAPI-KEY

Create or link a Rovas user (third-party integration)

For partner backends using an api client Rovas account: creates a new user or links
HybridAuth identity when the email already exists. Requires permission
access services_rules rules_create_user (api client / administrator roles).
JSON keys match Rules variables; optional hybridauth_provider defaults to Nabezky if empty.
Use GET /rovas/rovas_hybridauth_providers.json to list valid provider ids.

Request body (required)

Rule parameters (see rovas_site_rules README).

Content type: application/json, application/xml

RulesCreateUserRequest

  • user_name: string (required) — Display name for the new or linked Rovas user. (example: Jane Partner User)
  • user_id: integer (required) — External user id at the partner (HybridAuth provider_identifier). (example: 12345)
  • user_email: string (email) (required) — Used to find an existing Rovas account by mail.
  • user_country: string (required) — ISO 3166-1 alpha-2 code (e.g. SK). The rovas_partner_user endpoint requires uppercase ASCII letters only; the legacy Rules endpoint did not enforce casing.
  • user_language: string (required) — Language code; rule maps sk/cs to sk, default en. (example: en)
  • server_url: string (uri) (required) — Partner base URL for HybridAuth profile link (e.g. trailing slash optional per client). (example: https://partner.example/)
  • hybridauth_provider: string — HybridAuth provider machine name (e.g. Nabezky). Omit or empty for default Nabezky. Must be enabled on the site; use GET rovas_hybridauth_providers to list options.
  • partner_client_id: string — Optional metadata stored on the user (rovas_partner_client_id).

Responses

  • 200 — Rovas user id and rovas_endpoint API credentials for that user.

    RulesCreateUserResponse

    • rovas_uid: integer — Rovas user id (new or existing).
    • api_key: string — API key for rovas_endpoint for that user.
    • token: string — Token for rovas_endpoint for that user.
  • 401 — Missing or invalid API credentials.
  • 403 — Caller lacks permission to invoke this rule.
POST/rovas/rovas_partner_userAPI-KEY

Create or link a Rovas user (partner API, replaces rules_create_user)

Same purpose as POST /rovas/rules/rules_create_user, implemented as a native Services resource
for stricter validation and easier evolution. Requires permission
access services_rules rules_create_user and the same API client headers as other rovas_endpoint calls.
user_country must be two uppercase ASCII letters (ISO 3166-1 alpha-2) and must exist in the
site country list. user_language is normalized to an enabled Drupal interface language
(rovas_base_map_partner_user_language). Request body schema matches RulesCreateUserRequest.

Request body (required)

Same fields as rules_create_user (see RulesCreateUserRequest).

Content type: application/json, application/xml

RulesCreateUserRequest

  • user_name: string (required) — Display name for the new or linked Rovas user. (example: Jane Partner User)
  • user_id: integer (required) — External user id at the partner (HybridAuth provider_identifier). (example: 12345)
  • user_email: string (email) (required) — Used to find an existing Rovas account by mail.
  • user_country: string (required) — ISO 3166-1 alpha-2 code (e.g. SK). The rovas_partner_user endpoint requires uppercase ASCII letters only; the legacy Rules endpoint did not enforce casing.
  • user_language: string (required) — Language code; rule maps sk/cs to sk, default en. (example: en)
  • server_url: string (uri) (required) — Partner base URL for HybridAuth profile link (e.g. trailing slash optional per client). (example: https://partner.example/)
  • hybridauth_provider: string — HybridAuth provider machine name (e.g. Nabezky). Omit or empty for default Nabezky. Must be enabled on the site; use GET rovas_hybridauth_providers to list options.
  • partner_client_id: string — Optional metadata stored on the user (rovas_partner_client_id).

Responses

  • 200 — Rovas user id and rovas_endpoint API credentials for that user.

    RulesCreateUserResponse

    • rovas_uid: integer — Rovas user id (new or existing).
    • api_key: string — API key for rovas_endpoint for that user.
    • token: string — Token for rovas_endpoint for that user.
  • 400 — Validation error (country code, language, URL, email, provider, etc.).
  • 401 — Missing or invalid API credentials.
  • 403 — Caller lacks permission.
  • 500 — Server or registration failure.
POST/rovas/rules/rules_users_chronsAPI-KEY

Retrieves user's Chron balances.

Responses

  • 200 — If succesfull, returns the total and available user's chron balances

    UsersChronsResponse

    • total_chrons: number (float) — The total Chrons balance.
    • chrons_available: number (float) — The total Chrons balance minus all commitments to pay
POST/rovas/rules/rules_fetch_user_dataAPI-KEY

Retrieves user's Rovas profile info.

Responses

  • 200 — If succesfull, returns information from the user profile

    FetchUserDataResponse

    • country: string — 2-letter ISO country code in all caps
    • uid: integer (int32) — User ID
    • username: string — User name
    • lang_code: string — Two letter language code
    • email: string — Email
    • comp_score: integer (int32) — Compliance score
    • whole_name: string — Full name if available. Might be 'nomen omen' for users wo did not set their full name.
POST/rovas/rules/rules_user_s_meritsAPI-KEY

Retrieves user's total and taxonomy category-specific Merit balances. Set the nace_id param to 0 to return all Merits from the user's work reports. Retrieval error is indicated by value -1000000000.0000001 for either of the result parameters. Note that total_merits might differ from the term_merits when nace_id = 0 is passed to the endpoint.

Request body (required)

use Rovas NACE term ID as a parameter

Content type: application/json, application/xml

UsersMerits

  • nace_id: RovasTerms (required) — node ID of the NACE taxonomy term in Rovas

Responses

  • 200 — returns total and taxonomy-category-specific Merit balances

    UsersMeritsResponse

    • total_merits: number (float) — The total Merits balance.
    • term_merits: number (float) — The total Merit balance for the supplied term.
POST/rovas/rules/rules_check_enabled_languageAPI-KEY

Checks that a language identified by its 2-letter code is enabled

Request body (required)

Content type: application/json, application/xml

CheckEnabledLang

  • input: string (required) — two-letter language code in lower case (example: sk)

Responses

  • 200 — returns a 1 if the specified language is enabled

    CheckEnabledLangResponse

    • output: integer (0 | 1) — 0 - "language is enabled" 1 - "language is not enabled"
GET/rovas/rovas_hybridauth_providers.jsonPublic

List HybridAuth providers for account linking

Public endpoint: no API-KEY or TOKEN headers. Returns provider machine names
enabled in HybridAuth—the same values allowed as hybridauth_provider in
rules_create_user. The Services endpoint must have Disable API keys authentication
enabled for this resource operation (rovas_endpoint → Resources →
rovas_hybridauth_providers → index).

Parameters

  • Accept (header) — string (example: application/json)

Responses

  • 200 — Enabled providers for UI picker and for rules_create_user.hybridauth_provider.

    HybridAuthProvidersResponse

    • status: string
    • providers: array<HybridAuthProviderItem>
    {
      "status": "success",
      "providers": [
        {
          "id": "Nabezky",
          "name": "Nabezky"
        }
      ]
    }

Classic API — projects, work reports, verification

POST/rovas/rules/rules_proxy_create_new_projectAPI-KEY

Create a project

Request body (required)

Once a project is created, Rovas automatically creates also a new merit allocation document for the project owner.

Content type: application/json, application/xml

NewProject

  • project_name: string (required) (example: Test project title)
  • project_url: string (example: https://nabezky.sk/node/388383)
  • project_price: number (float) (example: 2.3)
  • project_status: integer (0 | 1 | 2 | 3) (required) — 0 unfinished, 1 for sale, 2 sold, 3 expired
  • project_participation: integer (0 | 1 | 2) (required) — 0 - Private, 1 - Public, 2 - Public - dependent on parent project
  • project_description: string (example: Report from a ski trip)

Responses

  • 200 — returns project/node ID of the created project

    NewProjectResponse

    • created_project_nid: integer — A greater than 0 new project ID.
POST/rovas/rules/rules_proxy_create_work_reportAPI-KEY

Create a work report in Rovas. Optional reward_kind and deferred usage fee for post-approval payout.

Request body (required)

Only the Web URL is supported as work evidence. Optional reward_kind (merits|chrons) and optional usage_fee_project_id + usage_fee_rate (both or neither) are persisted for post-approval payout. Merits is sticky on same-day merges; prefer deferred fee over a separate create_aur call when electing merits so fees come from WR proceeds before CHR→ME.

Content type: application/json, application/xml

NewWorkReport

  • wr_classification: RovasTerms (required) — node ID of the NACE taxonomy term in Rovas
  • wr_description: string — accepts HTML tags (example: Moved a big rock up the hill, but it fell back. Will continue rolling tomorrow.)
  • wr_activity_name: string (required) — title of work report - activity summary (example: Rock moving)
  • wr_hours: number (float) (required) — time in hours (example: 2.5)
  • wr_web_address: string (required) — URL of a proof for the work performed (example: https://nabezky.sk/node/3883)
  • parent_project_nid: integer (int64) (required) — parent project node ID (example: 28388348)
  • date_started: integer (int64) (required) — the date and time in UNIX timestamp format; must be within the last 30 days (example: 1594538979)
  • access_token: string — A text string of sufficient length and complexity that - when presented as URL argument 'cbt' attached to the address in the wr_web_address field - will allow unauthenticated access to the proof of work in that web page (example: 7JH_hdjd83%ks)
  • publish_status: integer (int64) (required) — if greater than 0, the report will be published; unpublished otherwise. No verifiers are invited for unpublished reports (example: 1)
  • reward_kind: string ("merits" | "chrons") — Payout preference after approval (peer verify or Trusted auto-approve). merits converts the Chron grant net of Rovas 1% and any deferred app fee to Merits (A6); chrons keeps Chrons. Same semantics as Civic civic_create_work_report. On same-day merges into one WR, merits is sticky (any merits session wins for the whole node, including later Chron top-ups). Omitted or invalid → chrons. (example: merits)
  • usage_fee_project_id: integer (int64) — Optional deferred app usage-fee beneficiary project nid. Must be paired with usage_fee_rate. Charged from WR Chron proceeds on approval (prefer this over rules_proxy_create_aur when reward_kind=merits). Invalid/unpublished → ignored (no fee). (example: 1998)
  • usage_fee_rate: number (float) — Optional deferred app usage-fee fraction in (0, 1], e.g. 0.03 for 3%. Must be paired with usage_fee_project_id. Merits conversion uses grant minus Rovas 1% minus this fee. (example: 0.03)

Responses

  • 200 — returns the new work report node ID

    NewWReportResponse

    • created_wr_nid: integer — A greater than 0 new work report ID, value 0 indicates the report is unpublished and no verifiers were invited; Error values: -1: author of the report is not a shareholder of the parent project; -2: the date_started is earlier that the date when the author registered in Rovas; -3: the report-filing author has more than one pending verification slot, so no verifiers were invited to verify the report; -4: date_started is more than 30 days before now;
POST/rovas/rules/rules_proxy_delete_work_reportAPI-KEY

Delete a work report

Request body (required)

If allowed, deletes a work report. Only own reports are deletable.

Content type: application/json, application/xml

DeleteWorkReport

  • wr_id: integer (int64) (required) — ID of the report (example: 123)

Responses

  • 200 — Returns 1 if deleted succesfully

    DeleteWorkReportResponse

    • result: integer (1 | -1) — returns: '1' if report deleted succesfully, '-1' not deleted - author of the report is different from the one making the call, or can not be deleted for other reason
POST/rovas/rules/rules_proxy_work_report_verifiabilityAPI-KEY

Finds out if work report is verifiable by an user

Request body (required)

The call finds out if report is verifiable and sets an environmental variable in Rovas that locks one of two/three verifiacation slots for 10 minutes.

Content type: application/json, application/xml

WorkReportVerifiability

  • wr_id: integer (int64) (required) — Rovas work report ID (example: 123)

Responses

  • 200 — returns 1 or 0

    VerifiabilityResponse

    • verifiable: boolean (1 | 0) — 1 - "if report is verifiable by the user" 0 - "if report is NOT verifiable"
    • reason: integer (1 | -1) — 1 - "no problem found when checking" -1 - "the work report can not be found"
POST/rovas/rules/rules_proxy_report_editabilityAPI-KEY

Finds out if work report is editable by an user

Request body (required)

The call determines if a report can be edited by the user identified by the API key and the token.

Content type: application/json, application/xml

Editability

  • wr_id: integer (int64) (required) — Rovas work report ID (example: 123)

Responses

  • 200 — returns 1 or 0

    EditabilityResponse

    • result: integer (1 | -1) — 1 - "if report is editable by the user 0 if not editable" -1 - "if the work report can not be found"
POST/rovas/rules/rules_create_verificationAPI-KEY

Create a verification record

Request body (required)

Creates a verification record for the work report.

Content type: application/json, application/xml

CreateVerification

  • wr_id: integer (int64) (required) (example: 123)
  • verdict: integer (0 | 1) (required) — verification result; 0 - rejected, 1 - approved (example: 1)

Responses

  • 200 — returns verification record ID if successful, -1 otherwise

    VerificationResponse

    • verification_id: integer — returns the new verification ID if succesfull, '-2' if the report can not be found, '-3' if the report is not verifiable by the user.
POST/rovas/rules/rules_create_verification_with_acccess_tokenPublic

Create a verification record

Request body (required)

Creates a verification record for the work report using access token and Rovas user ID. No API-KEY and TOKEN are needed in header.

Content type: application/json, application/xml

CreateVerificationAT

  • access_token: string (required) — access token of the verified work report (example: 143ac8d45c7b8a6cc020)
  • uid: integer (required) — Rovas ID of the verifier (example: 289)
  • wr_id: integer (int64) (required) — The verified work report ID (example: 123)
  • verdict: integer (int32) (required) — verification result; 0 - rejected, 1 - approved (example: 1)

Responses

  • 200 — returns verification record ID if successful

    VerificationATResponse

    • verification_id: integer (int64) — Returns the verification node ID if successful, '-1' if user does not exist with the supplied ID, '-2' if the access token supplied is invalid, '-3' if there does not exist a verification slip for the access token and UID, or the supplied work report ID does not match the report ID found from the access token
POST/rovas/rules/rules_proxy_reward_work_reportAPI-KEY

Reward a work report

Request body (required)

Rewards a work repor with merits equal to the chrons sent by the user identified by the API key and token sent in the header

Content type: application/json, application/xml

WorkReportReward

  • report_id: integer (int64) (required) — Rovas work report ID (example: 123)
  • reward_amount: number (float) (required) (example: 2.3)
  • description: string (required) — Any note related to the reward (example: A work report reward made by <REST client app name> user)

Responses

  • 200 — returns one of 0 or 1 as well as text explaining the ourcome

    WorkReportRewardResponse

    • result: integer (int32) — 1 - "for success" 0 - "for failure"
    • result_explain: string — the reason of failure in plain english
POST/rovas/rules/rules_proxy_delete_projectAPI-KEY

Delete a project

Request body (required)

Deletes a project and all related work reports, merit allocation shares and disputes.

Content type: application/json, application/xml

DeleteProject

  • project_id: integer (int64) (required) — ID of the project (example: 123)

Responses

  • 200 — the 'result' parameter indicates the status of the operation - 0 for failure or 1 for success. The 'result_explain' parameter informs about the reason for failure if the project was not deleted.

    DeleteProjectResponse

    • result: integer (0 | 1 | null) — 1 - "success" 0 - "failure" * null - "returned if the API KEY and TOKEN supplied in the header do not belong to user with the 'api client' Rovas role "
    • result_explain: integer (0 | 1 | 2) — 0 - "no error" 1 - "deleting project not allowed" * 2 - "project not found for the given ID"
POST/rovas/rules/rules_proxy_report_verification_statusAPI-KEY

Get a work report verification status

Request body (required)

Returns a count of verifications made and an integer indicating the number of approved verifications.

Content type: application/json, application/xml

GetVerifStatus

  • wr_id: integer (int64) (required) — Work report ID (example: 123)

Responses

  • 200 — the count_total shows the number of verifications and the result parameter encodes the number of approved ones

    GetVerifStatusResponse

    • result: integer (0 | -1 | 1 | -3 | -4 | -5) — 0 - "0 approvals" -1 - "one approval" 1 - "more than one approval" -3 - "work report can not be found with the supplied ID"
    • count_total: integer (-1 | 0 | 1 | 2 | 3) — the number of verifications made for the work report; a negative number indicates an error during processing of the request, explained by the 'result' parameter;
POST/rovas/rules/rules_proxy_check_verifier_by_access_tokensAPI-KEY

given access token and verifier ID, determines verifiability of a work report

Request body (required)

Returns TRUE if a verification slip exists for the tokens supplied

Content type: application/json, application/xml

CheckVerifAccessTokens

  • access_token: string (required) — access token of the verified report (example: 143ac8d45c7b8a6ac054)
  • uid: integer (required) — Verifier Rovas user ID (example: 289)

Responses

  • 200 — returns 1 if user can verify the content

    CheckVerifAccessTokensResponse

    • verify_allow: integer (1 | 0) — 1 - "user can verify the content" 0 - "user can not verify the content"
GET/rovas/rovas_verifications.jsonAPI-KEY

Get list of work report verifications

Parameters

  • Accept (header) — string — Expected response format. (example: application/json)
  • Content-Type (header) — string — Content type of the request. (example: application/json)

Responses

  • 200 — JSON encoded array of verifications

    VerificationsResponse

    • status: string
    • count: integer
    • verifications: array<VerificationItem>
    {
      "status": "success",
      "count": 41,
      "verifications": [
        {
          "report_nid": "429357",
          "report_title": "Creating map data with JOSM",
          "verify_date": "1753086074",
          "verify_date_formatted": "Mon, 07/21/2025 - 10:21",
          "report_url": "https://dev.rovas.app/node/429357"
        },
        {
          "report_nid": "429454",
          "report_title": "Creating map data with JOSM",
          "verify_date": "1753086073",
          "verify_date_formatted": "Mon, 07/21/2025 - 10:21",
          "report_url": "https://dev.rovas.app/node/429454"
        }
      ]
    }
GET/rovas/rovas_comment_notices.jsonAPI-KEY

Get pending watched-comment notices

Pending in-app/API notices for new comments on nodes the key owner is watching
(same Comment Notify audience as follow-up email). Poll-based; not an outbound
webhook. Twin of Bearer GET /rovas/civic_pending_comment_notices (different
response envelope). Requires module rovas_comment_watch. Path is
/rovas/rovas_comment_notices (not under /rovas/rules/).

Parameters

  • Accept (header) — string — Expected response format. (example: application/json)

Responses

  • 200 — JSON list of pending comment notices for the authenticated user

    CommentNoticesResponse

    • status: string
    • count: integer
    • notices: array<CommentNoticeItem>
    {
      "status": "success",
      "count": 1,
      "notices": [
        {
          "nid": 123,
          "node_title": "Example post",
          "cid": 456,
          "comment_url": "https://dev.rovas.app/comment/456",
          "created": 1729100000
        }
      ]
    }
  • 401 — Missing or invalid API-KEY / TOKEN
  • 500 — Comment watch module unavailable or query failure

Classic API — shares, purchases, conversions

POST/rovas/rules/rules_proxy_create_aurAPI-KEY

[Deprecated] Create an asset usage record (app/product usage fee)

Deprecated for work-report app fees. Prefer deferred usage_fee_project_id +
usage_fee_rate on POST /rovas/rules/rules_proxy_create_work_report (one call).
That charges the fee from WR Chron proceeds on approval and, when
reward_kind=merits, subtracts it before CHR→ME — so merits-only reporters
are not left with a negative Chron balance. A separate create_aur after a
Merits payout debits the Chron wallet and can go negative.
Still valid for non-WR / legacy AUR charges.

Request body (required)

Creates an asset usage record charging the work-report author (Chron wallet).

Content type: application/json, application/xml

CreateAUR

  • project_id: integer (int64) (required) — The beneficiary project ID (example: 123)
  • wr_id: integer (int64) (required) — The ID of a work report that uses the product or service delivered by the beneficiary project (example: 123)
  • usage_fee: string (required) — the fee paid by the work report creator for usage of the product or service described in the beneficiary project (example: 9.23)
  • note: string — an optional note (example: 3% fee levied by the 'Obsidian hand axe' project for using the axe)

Responses

  • 200 — returns AUR record ID if successful, 0 or -1 otherwise

    CreateAURResponse

    • result: integer (int32) — success: an integer greater than 0 denoting the AUR ID. 'null' is returned if entities do not exist for the supplied IDs, or the usage fee is empty; '0' if work report was not found for the supplied ID; '-1' if the work report owner is not the same as the user;
POST/rovas/rules/rules_proxy_purchase_productAPI-KEY

Process purchase of a product.

Request body (required)

Creates purchase receipts, processes Chron transactions, distributes Merits to shareholders and (optionally Chrons to the project owner).

Content type: application/json, application/xml

NewPurchase

  • product_id: integer (int64) (required) — Rovas product ID (example: 123)
  • amount_paid: number (float) (required) (example: 2.3)
  • note: string (required) — Any note related to purchase (example: Purchase made by <REST client app name> user)

Responses

  • 200 — returns an integer indicating the operation outcome

    PurchaseResponse

    • result: integer (1 | -1 | -2 | -3) — 1 - "for success" -1 - "the amount paid is negative or 0 (no purchase was made)" -2 - "no enough funds to buy the product" -3 - "product not found for the supplied ID"
POST/rovas/rules/rules_get_merits_for_projectsAPI-KEY

Takes a list of Rovas project IDs separated by pipe and returns current merit value for each of the projects.

Request body (required)

Content type: application/json, application/xml

ProjectMerits

  • project_ids: string (required) — pipe separated project IDs (example: 2410|2421)

Responses

  • 200 — returns a json-encoded string of project IDs and their merits;

    ProjectMeritsResponse

    • project_merits: string — json-encoded string containig rovas project IDs and their current merit rating. Error states: '-1' - the supplied IDs are in an incorrect format; empty set is returned if no projects were found for the supplied IDs
POST/rovas/rules/rules_convert_euros_to_chronsAPI-KEY

Returns the amount of Chrons one can buy with the given Euros.

Request body (required)

Content type: application/json, application/xml

ConvertChrons

  • euros: number (float) (required) — The Euro amount (example: 3.14159)

Responses

  • 200 — returns a decimal representing the Chron amount

    ConvertChronsResponse

    • chrons: number (float) — The amount of Chrons converted to Euros. Negative values are made positive and subsequently converted.
POST/rovas/rules/rules_convert_euros_to_chrons_reverseAPI-KEY

Returns the amount of Chrons one has to pay to receive the given Euros.

Request body (required)

Content type: application/json, application/xml

ConvertChrons

  • euros: number (float) (required) — The Euro amount (example: 3.14159)

Responses

  • 200 — returns a decimal representing the Chron amount, or -1 if user not found, or -2 if the euro amount exceeds the number of Euros available for exchange in Rovas;

    ConvertChronsResponse

    • chrons: number (float) — The amount of Chrons converted to Euros. Negative values are made positive and subsequently converted.
POST/rovas/rules/rules_proxy_check_or_add_shareholderAPI-KEY

Checks that user is shareholder in a project. If not and possible, makes the user a shareholder.

Request body (required)

Content type: application/json, application/xml

CheckAddShareholder

  • project_id: integer (int64) (required) (example: 838938)

Responses

  • 200 — returns the Merit allocation node ID if successfull and 0 or negative integer otherwise

    CheckAddShareholResponse

    • result: integer (int32) — returns a Worker Merit Allocation node ID if the user is a shareholder, '0' if project is private and user can not add themselves, '-1' if project does not exist
POST/rovas/rules/rules_proxy_check_or_add_project_shareholderAPI-KEY

Checks that a project is a shareholder in a project. If not and possible, creates time, or percentage-based share.

Request body (required)

Content type: application/json, application/xml

CheckAddProjectShareholder

  • project_nid: integer (int64) (required) — project ID (example: 838938)
  • shareholder_proj_nid: integer (int64) (required) — shareholder project ID (example: 838938)
  • time_based: integer (1 | 0) (required) — 1 - time-based; 0 - percent-based (example: 1)
  • merit_share: number (float) (required) — the desired merit share in % (example: 3.14159)

Responses

  • 200 — returns the Merit allocation node ID if successfull and a negative integer otherwise

    CheckAddProjectShareholResponse

    • result: integer (int32) — returns the Project Merit Allocation node ID for the shareholder project, '-1' if the project author is not the API and Token owner, '-2' if a project does not exist with the project_nid given, '-3' if a project does not exist with the shareholder_proj_nid given, '-4' if the project shareholder being added isn already a shareholder, or the total shares exceeds 100 for non-time-based shareholder

Classic API — leaderboard / feed Views

GET/rovas/views/top_10_workers_in_a_categoryAPI-KEY

Get top x workers in a given category.

Parameters

  • display_id (query, required) — string — the view display ID.
  • filters[tid_raw] (query) — Rovas category node ID (example: 1794)
  • filters[field_web_address_value] (query) — string — The work report source url (example: nabezky.sk)
  • limit (query) — integer — the number of records to be returned. If omitted, 10 records are returned (example: 10)

Responses

  • 200 — json encoded array

    string

GET/rovas/views/project_merits_feedAPI-KEY

Get top x users, who rewarded a project

Parameters

  • display_id (query, required) — string — the view display ID.
  • filters[project_id] (query, required) — integer — Rovas project ID (example: 12900)
  • limit (query) — integer — the number of records to be returned. If omitted, 1 record is returned (example: 10)

Responses

  • 200 — json encoded array of Rovas user ID, user name and the merits earned

    string

GET/rovas/views/projects_meritsAPI-KEY

Get top x users, for projects from the same web site

Parameters

  • display_id (query, required) — string — the view display ID.
  • filters[field_asset_web_address_value] (query, required) — string — a part of the url the project refers to (example: nabezky.sk/node/)
  • limit (query) — integer — the number of records to be returned. (example: 10)

Responses

  • 200 — json encoded array of: rank in the hierarchy, Rovas user ID, merit score for the user and the number of projects that share the same field_asset_web_address_value

    string

Classic API — allowlisted node retrieve/update/delete

GET/rovas/node/{id}API-KEY

Retrieve basic fields for an allowlisted node type

Returns a sanitized payload for types project, work_report,
charity_organization, or dispute only. Other types (and missing
nids) return 404. Does not dump the full Drupal node object.
Project responses include is_public; work_report responses include
project_nid when set.

Parameters

  • id (path, required) — integer — the node ID

Responses

  • 200 — Sanitized node summary

    RetrieveNodeResponse

    • nid: integer
    • type: string ("project" | "work_report" | "charity_organization" | "dispute")
    • title: string
    • status: integer — 1 = published, 0 = unpublished
    • uid: integer — Author Drupal uid
    • created: string (date-time)
    • changed: string (date-time)
    • language: string — Drupal langcode; null when empty or und
    • url: string (uri)
    • is_public: boolean — Present for type=project (participation Public or Public-dependent)
    • project_nid: integer — Present for type=work_report; linked project nid when set
  • 401 — Missing or invalid API-KEY / TOKEN
  • 403 — Authenticated but not allowed to view the node
  • 404 — Missing nid or type not in the allowlist
PUT/rovas/node/{id}API-KEY

Updates a node owned by the user whose credentials are supplied in the header

Parameters

  • id (path, required) — integer — the node ID

Request body (required)

Updates a node with an ID given in the URL paramater.

Content type: application/json, application/xml

UpdateNode

  • field_hours_worked: UndSchema (required) — language of the field. 'und' stands for not specified

Responses

  • 200 — If succesfull returns the node ID and URL of the updated node.

    UpdateNodeResponse

    • nid: integer — node ID of the updated node
    • uri: string — URL of the updated node
DELETE/rovas/node/{id}API-KEY

Deletes a node owned by the user whose credentials are supplied in the header

Parameters

  • id (path, required) — integer — the node ID

Responses

  • 200 — If succesfull returns the boolean TRUE.

OAuth / Civic endpoints

OAuth 2 protocol (authorize, token, revoke, introspect)

GET/oauth2/authorizePublic

OAuth 2 authorization endpoint (browser)

Browser authorization with PKCE. Civic supports query extras lang=sk|en and intent=login|register.

Civic client (reference): client_id=civic, public (no secret), grants authorization_code + refresh_token, PKCE S256, scope user_profile, redirect civic://oauth/callback.

Parameters

  • response_type (query, required) — string
  • client_id (query, required) — string
  • redirect_uri (query, required) — string
  • scope (query) — string
  • state (query) — string
  • code_challenge (query, required) — string
  • code_challenge_method (query, required) — string
  • lang (query) — string
  • intent (query) — string — Land on login vs register.

Responses

  • 302 — Redirect to login/consent or back to redirect_uri with code
POST/oauth2/tokenPublic

Exchange authorization code or refresh token

Public client + PKCE. Use application/x-www-form-urlencoded body.

Request body (required)

Content type: application/x-www-form-urlencoded

OAuthTokenRequest

  • grant_type: string ("authorization_code" | "refresh_token") (required)
  • client_id: string (required) (example: civic)
  • redirect_uri: string (example: civic://oauth/callback)
  • code: string — Required for authorization_code
  • code_verifier: string — PKCE verifier for authorization_code
  • refresh_token: string — Required for refresh_token

Responses

  • 200 — Token pair

    OAuthTokenResponse

    • access_token: string
    • token_type: string
    • expires_in: integer
    • refresh_token: string
    • scope: string
  • 400 — Invalid grant or request
POST/oauth2/revokePublic

Revoke access or refresh token

Request body (required)

Content type: application/x-www-form-urlencoded

object

  • token: string (required)
  • token_type_hint: string ("access_token" | "refresh_token")
  • client_id: string (example: civic)

Responses

  • 200 — Revoked (or already invalid)
GET/oauth2/tokens/{access_token}Public

Introspect access token

Returns user_id, client_id, expires, scope. 404 if invalid.

Parameters

  • access_token (path, required) — string

Responses

  • 200 — Token metadata

    OAuthTokenIntrospection

    • user_id: integer — Drupal uid
    • client_id: string
    • expires: integer — Unix expiry
    • scope: string
  • 404 — Invalid or unknown token

OAuth / Civic — home, profile, preferences

GET/rovas/meBearer

Current user profile (Bearer)

Profile for the OAuth-authenticated user. Includes Merit/Chron totals, receipt history retention, ME sources share preference, and Trusted user notify state.

Parameters

  • Accept (header) — string (example: application/json)

Responses

  • 200 — Profile

    MeResponse

    • uid: integer
    • username: string
    • display_name: string
    • total_me: number (float)
    • total_chr: number (float)
    • created: string (date-time)
    • language: string
    • receipt_history_retention: string ("keep" | "policy") | null — null | keep | policy
    • me_sources_share: string ("everyone" | "reciprocal" | "aggregate")
    • trusted_user: boolean
    • trusted_notify: integer (0 | 1 | 2) — 0=no banner, 1=show, 2=dismissed
    {
      "uid": 42,
      "username": "example_user",
      "display_name": "Example User",
      "total_me": 1248.35,
      "total_chr": 320,
      "created": "2019-03-12T14:22:01+00:00",
      "language": "sk",
      "receipt_history_retention": null,
      "me_sources_share": "everyone",
      "trusted_user": false,
      "trusted_notify": 0
    }
  • 401 — Missing or invalid Bearer
GET/rovas/contributions/aggregatePublic

Community Merit total

Public aggregate community Merit total (+ category placeholders).

Parameters

  • Accept (header) — string (example: application/json)

Responses

  • 200 — Aggregate Merits JSON
GET/rovas/merit_distributionOptional Bearer

Merit histogram

Public Merit distribution histogram. Optional Bearer adds user_* fields for the authenticated caller.

Parameters

  • Accept (header) — string (example: application/json)

Responses

  • 200 — Histogram JSON; may include user_* when Bearer present
POST/rovas/civic_receipt_history_preferenceBearer

Set receipt history retention

Body: { "retention": "keep" | "policy" } (90-day policy when policy).

Request body (required)

Content type: application/json

ReceiptHistoryPreferenceRequest

  • retention: string ("keep" | "policy") (required)

Responses

  • 200 — Updated preference

    ReceiptHistoryPreferenceResponse

    • receipt_history_retention: string ("keep" | "policy")
  • 401 — Missing or invalid Bearer
POST/rovas/civic_me_sources_preferenceBearer

Set ME sources share preference

Who may see detailed tax/gift ME mix: everyone | reciprocal | aggregate.

Request body (required)

Content type: application/json

MeSourcesPreferenceRequest

  • share: string ("everyone" | "reciprocal" | "aggregate") (required)

Responses

  • 200 — Updated preference

    MeSourcesPreferenceResponse

    • me_sources_share: string ("everyone" | "reciprocal" | "aggregate")
  • 401 — Missing or invalid Bearer
POST/rovas/civic_give_chronsBearer

Convert Chrons to Merits 1:1 (A6)

Voluntary CHR→ME conversion. Body { "amount": <positive number> }.

Request body (required)

Content type: application/json

GiveChronsRequest

  • amount: number (float) (required) — Positive Chrons to convert (1:1 to Merits)

Responses

  • 200 — Conversion result

    GiveChronsResponse

    • chrons_given: number (float)
    • merits_gained: number (float)
    • total_chr: number (float)
    • total_me: number (float)
  • 401 — Missing or invalid Bearer
  • 422 — Invalid amount or insufficient_chrons
POST/rovas/civic_dismiss_trusted_notifyBearer

Dismiss Trusted user congratulations banner

Sets trusted_notify to 2. Empty JSON body OK.

Request body

Content type: application/json

object

Responses

  • 200 — Notify state

    TrustedNotifyDismissResponse

    • trusted_user: boolean
    • trusted_notify: integer (0 | 1 | 2)
  • 401 — Missing or invalid Bearer
GET/rovas/civic_merit_historyBearer

Caller Merit ledger rows

Parameters

  • Accept (header) — string (example: application/json)

Responses

  • 200 — Merit history rows for the Bearer user
  • 401 — Missing or invalid Bearer

OAuth / Civic — user search and community lookup

GET/rovas/users_lookupBearer

Community profile by username

Exact username. Includes nace_expertise, tab aggregates (top_charities, top_volunteer_projects, …). ME-mix detail respects me_sources_share. Users with total_me < 0 → 404. Optional lang=sk|en.

Parameters

  • Accept (header) — string (example: application/json)
  • username (query, required) — string
  • lang (query) — string

Responses

  • 200 — Public community profile
  • 401 — Missing or invalid Bearer
  • 404 — Unknown user or total_me < 0

OAuth / Civic — tax claims (Path 1) and national rate

POST/rovas/rules/rules_proxy_claim_vat_receiptBearer

Claim eKasa VAT as donor Merits

Bearer-only Rules proxy. Split Merits across projects via shares[]. API-key auth is disabled on this resource.

Request body (required)

Content type: application/json

ClaimVatReceiptRequest

  • receipt_uid: string
  • shares: array<object>

Responses

  • 200 — Claim result

    ClaimVatReceiptResponse

    • claimed: boolean
    • receipt_uid: string
    • merits: number (float)
  • 400 — Validation error
  • 401 — Missing or invalid Bearer
GET/rovas/civic_claimsBearer

Claim lists or receipt status

With view=submitted|received: claim lists (optional merchant / date / VAT filters). With receipt_uid=: returns { claimed, receipt_uid } only.

Parameters

  • Accept (header) — string (example: application/json)
  • view (query) — string
  • receipt_uid (query) — string
  • merchant (query) — string
  • date_from (query) — string
  • date_to (query) — string

Responses

  • 200 — Claim list or receipt status
  • 401 — Missing or invalid Bearer
GET/rovas/civic_claims/summaryBearer

Claim totals for caller

Parameters

  • Accept (header) — string (example: application/json)

Responses

  • 200 — Summary totals
  • 401 — Missing or invalid Bearer
GET/rovas/civic_national_hourly_ratePublic

National hourly rate for ME formula

Parameters

  • Accept (header) — string (example: application/json)
  • country (query, required) — string

Responses

  • 200 — Hourly rate for country

OAuth / Civic — project detail, charity catalog, gifts

GET/rovas/civic_project/{nid}Public

Project detail (Civic)

Includes donate_iban, org fields (org_id, country, website_url, iban_verified), … Anonymous allowed for NeoFund-approved public-benefit projects; otherwise Bearer / access rules apply. Optional lang=.

Parameters

  • Accept (header) — string (example: application/json)
  • nid (path, required) — integer
  • lang (query) — string

Responses

  • 200 — Project detail
  • 404 — Not found or not readable
GET/rovas/civic_project_work_reportsPublic

Work reports for a project

Anonymous allowed for approved public-benefit projects; otherwise Bearer. Optional lang=.

Parameters

  • Accept (header) — string (example: application/json)
  • project_nid (query, required) — integer
  • lang (query) — string

Responses

  • 200 — Work report list (may include photo_urls[])
GET/rovas/civic_project_shareholdersPublic

Project shareholders

Anonymous allowed for approved public-benefit projects; otherwise Bearer.

Parameters

  • Accept (header) — string (example: application/json)
  • project_nid (query, required) — integer

Responses

  • 200 — Shareholder list
GET/rovas/civic_charity_projectsPublic

Approved public-benefit project catalog

Parameters

  • Accept (header) — string (example: application/json)

Responses

  • 200 — Charity project catalog
POST/rovas/civic_create_charity_orgBearer

Donor submits a public-benefit organization

Bearer required. SK orgs may auto-verify; claim email flow applies.

Request body (required)

Content type: application/json

object

Responses

  • 200 — Created org / project linkage
  • 401 — Missing or invalid Bearer

OAuth / Civic — volunteer work reports

GET/rovas/civic_my_projectsBearer

Recent projects the user reported on

Parameters

  • Accept (header) — string (example: application/json)

Responses

  • 200 — Project list
  • 401 — Missing or invalid Bearer
GET/rovas/civic_nace_treePublic

NACE activity tree

Parameters

  • Accept (header) — string (example: application/json)

Responses

  • 200 — NACE tree JSON
POST/rovas/civic_create_projectBearer

Create project (Bearer)

Body: name, description, optional url. Do not use classic API-KEY project rules from Civic.

Request body (required)

Content type: application/json

CivicCreateProjectRequest

  • name: string (required)
  • description: string (required)
  • url: string

Responses

  • 200 — Created project

    CivicCreateProjectResponse

    • nid: integer
  • 401 — Missing or invalid Bearer
POST/rovas/civic_create_work_reportBearer

Create work report (Bearer)

Proof required: URL and/or photos and/or map (field_location GeoJSON Point, LineString, Polygon, or GeometryCollection). Clients should redact photos before upload; photo_redact_mode is ignored if present.

Request body (required)

Content type: application/json

CivicCreateWorkReportRequest

  • project_nid: integer (required)
  • date_started: string (required) — Work start date
  • hours: number (float) (required)
  • description: string (required)
  • nace_tid: integer (required)
  • title: string
  • web_url: string — Work evidence URL
  • photos: array<string> — Base64 proof photos (client-redacted)
  • reward_kind: string — merits or chrons after approval (Trusted auto-approve or peer verify); merits sticky if WR is merged
  • field_location: object — GeoJSON geometry: Point, LineString, Polygon, or GeometryCollection
  • usage_fee_project_id: integer
  • usage_fee_rate: number (float)
  • photo_redact_mode: string — Ignored if present; redact on the client before upload

Responses

  • 200 — Created work report

    CivicCreateWorkReportResponse

    • nid: integer
  • 400 — Validation error
  • 401 — Missing or invalid Bearer
GET/rovas/civic_work_report_map_configBearer

Map widget config for location proof

Parameters

  • Accept (header) — string (example: application/json)

Responses

  • 200 — Basemap / centre / geometry types
  • 401 — Missing or invalid Bearer
POST/rovas/civic_ai_naceBearer

AI NACE + title suggestion

Optional rovas_ai module. Clients should fall back to NACE tree when unavailable.

Request body (required)

Content type: application/json

object

Responses

  • 200 — Suggestion or unavailable
  • 401 — Missing or invalid Bearer

OAuth / Civic — verification and notifications

GET/rovas/civic_pending_verificationsBearer

Work reports assigned to caller to verify

Parameters

  • Accept (header) — string (example: application/json)
  • lang (query) — string

Responses

  • 200 — Pending verification slots
  • 401 — Missing or invalid Bearer
GET/rovas/civic_work_report/{nid}Bearer

Verifier-facing work-report detail

Parameters

  • Accept (header) — string (example: application/json)
  • nid (path, required) — integer
  • lang (query) — string

Responses

  • 200 — Work report detail for verifier
  • 401 — Missing or invalid Bearer
  • 403 — No assigned verification slot
POST/rovas/civic_submit_verificationBearer

Approve / reject / decline verification

Request body (required)

Content type: application/json

CivicSubmitVerificationRequest

  • work_report_nid: integer
  • decision: string ("approve" | "reject" | "decline")
  • comment: string

Responses

  • 200 — Verification submitted
  • 401 — Missing or invalid Bearer
GET/rovas/civic_pending_comment_noticesBearer

Polled watched-comment notices

Same Comment Notify audience as email; poll-based (rovas_comment_watch). Classic twin: GET /rovas/rovas_comment_notices.json.

Parameters

  • Accept (header) — string (example: application/json)

Responses

  • 200 — Pending notices
  • 401 — Missing or invalid Bearer

OAuth / Civic — Merit index and spotlight (public)

GET/rovas/civic_merit_indexPublic

Snapshot Merit leaderboard

Includes by_category, by_source, … Snapshot rebuilt periodically (cron).

Parameters

  • Accept (header) — string (example: application/json)

Responses

  • 200 — Leaderboard snapshot
GET/rovas/civic_merit_index_countriesPublic

Country filter options for Merit index

Parameters

  • Accept (header) — string (example: application/json)

Responses

  • 200 — Country list
GET/rovas/civic_merit_spotlightPublic

Period leads by Civic area

Parameters

  • Accept (header) — string (example: application/json)
  • period (query) — string

Responses

  • 200 — Spotlight leads
GET/rovas/civic_merit_period_indexPublic

ME•ter period leaderboard

Parameters

  • Accept (header) — string (example: application/json)

Responses

  • 200 — Period leaderboard