Configuration File

Riposte reads platform settings from a single JSON document at riposte/sync.config.json. The file now focuses on operational wiring for the hosted admin experience—database connectivity, webhook delivery, OAuth credentials, and branding for the hosted authentication flow. All options live alongside your source code so changes are easy to review and track.

Quick start

A minimal riposte/sync.config.json:

{
  "riposte": {
    "database": {
      "url": "env:DATABASE_URL"
    },
    "notifications": {
      "default": "webhook"
    },
    "webhooks": {
      "primary": {
        "url": "https://example.com/webhook",
        "isActive": true
      }
    },
    "oauth": {
      "google": {
        "clientId": "env:GOOGLE_CLIENT_ID",
        "clientSecret": "env:GOOGLE_CLIENT_SECRET",
        "redirectUri": "env:GOOGLE_REDIRECT_URI"
      }
    },
    "app": {
      "adminEnabled": true,
      "redirectUrl": "http://localhost:3000/accounts"
    }
  }
}

Add only the blocks you need—missing sections fall back to the built-in defaults shipped with Riposte.

Key sections

The riposte object contains the strongly typed platform configuration. Common sub-sections include:

• riposte.database – Connection string and optional pooling controls for the sync datastore.
• riposte.migrations – Decide whether Riposte runs pending migrations at startup. autoApply defaults to true; set it to false when you want to manage migrations outside of the server lifecycle.
• riposte.notifications – Choose webhook versus polling delivery and tune polling cadence.
• riposte.webhooks – Define named webhook targets with secrets, headers, retries, and timeouts.
• riposte.oauth – Store OAuth redirect URIs and reference environment variables for client credentials.
• riposte.googleCloud – Configure Pub/Sub integration for Gmail push notifications.
• riposte.logging.openTelemetry – Enable OTLP log export and specify collector headers or endpoints.
• riposte.app – Control redirects for the hosted admin portal.
• riposte.authScreen – Brand the hosted authentication experience.
• riposte.messageTracking – Enable tracking pixels or headers and supply the supported domains.

Environment-specific overrides remain optional—add an environments object if you need to tailor riposte.* settings for specific deployments.

Working with the CLI helpers

Install dependencies and run the helper from the project root:

npm install
npx riposte-config lint

Useful commands:

• riposte-config lint – Validates the file, prints warnings, and shows the effective merge for the active environment.
• riposte-config explain <path> – Describes a specific key (for example riposte.notifications.default).
• riposte-config fields --search <term> – Lists all known keys from the shared metadata table.

All commands accept --file to point at a different config and --env to evaluate another environment.

API endpoints

7 endpoints

Email synchronization operations

DELETE /cursor-sync/accounts/{accountId}/config

Reset account cursor sync configuration to global defaults

Reset a specific account's cursor sync configuration to use the global defaults.

Parameters

accountId string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

Returns

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X DELETE "http://localhost:8080/cursor-sync/accounts/{accountId}/config"
                  
              

Example response 200

No example response available.

---

GET /cursor-sync/accounts/{accountId}/config

Get cursor sync configuration for an account

Retrieve the cursor-based synchronization configuration for a specific email account.

Parameters

accountId string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

Returns

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/cursor-sync/accounts/{accountId}/config"
                  
              

Example response 200

No example response available.

---

POST /cursor-sync/accounts/{accountId}/config

Configure cursor sync for an account

Set cursor-based synchronization configuration for a specific email account.

Parameters

accountId string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

Request body

Optional • application/json

Request body (application/json)

post-/cursor-sync/accounts/{accountId}/config-request-body-application/json

object<{ mode, slidingWindowMs, maxObjectUpdates }>

Field	Type	Description	Values
maxObjectUpdates Optional	number	Maximum number of object updates to include in one webhook ≥ 1 • ≤ 100	—
mode Optional	string	Sync mode: mailbox-level or object-level notifications mailboxobject	—
slidingWindowMs Optional	number	Sliding window duration in milliseconds for batching rapid updates ≥ 100 • ≤ 30000	—

Returns

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X POST "http://localhost:8080/cursor-sync/accounts/{accountId}/config" \
                  
                    2
                      -H "Content-Type: application/json"
                  
              

Example response 200

No example response available.

---

GET /cursor-sync/accounts/configs

Get all account cursor sync configurations

Retrieve cursor sync configurations for all accounts along with the global configuration.

Parameters

This endpoint does not accept parameters.

Returns

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/cursor-sync/accounts/configs"
                  
              

Example response 200

No example response available.

---

GET /cursor-sync/global/config

Get global cursor sync configuration

Retrieve the current global default configuration for cursor-based synchronization.

Parameters

This endpoint does not accept parameters.

Returns

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/cursor-sync/global/config"
                  
              

Example response 200

No example response available.

---

POST /cursor-sync/global/config

Configure global cursor sync defaults

Set global default configuration for cursor-based synchronization across all accounts.

Parameters

This endpoint does not accept parameters.

Request body

Optional • application/json

Request body (application/json)

post-/cursor-sync/global/config-request-body-application/json

object<{ mode, slidingWindowMs, maxObjectUpdates }>

Field	Type	Description	Values
maxObjectUpdates Optional	number	Default maximum number of object updates to include in one webhook ≥ 1 • ≤ 100	—
mode Optional	string	Default sync mode: mailbox-level or object-level notifications mailboxobject	—
slidingWindowMs Optional	number	Default sliding window duration in milliseconds for batching rapid updates ≥ 100 • ≤ 30000	—

Returns

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X POST "http://localhost:8080/cursor-sync/global/config" \
                  
                    2
                      -H "Content-Type: application/json"
                  
              

Example response 200

No example response available.

---

GET /cursor-sync/status

Get cursor sync status

Retrieve the current status of cursor-based synchronization including active sliding windows.

Parameters

This endpoint does not accept parameters.

Returns

Default Response

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/cursor-sync/status"
                  
              

Example response 200

No example response available.