API & Exports

Authentication

All REST API requests require a Bearer token. Generate API keys from your Integrations dashboard. Keys are scoped to your organization — all data returned is org-scoped automatically.

Authorization: Bearer rfk_live_<your_api_key>

curl -H "Authorization: Bearer rfk_live_abc123..." \
  https://rollforgeops.ai/api/v1/portcos

Rate Limits

1,000 requests per hour per API key. Limit resets at the top of each UTC hour.

When you exceed the limit you receive a 429 Too Many Requests response. Back off and retry after the window resets.

# 429 response
{
  "error": "Rate limit exceeded: 1000 requests/hour"
}

Pagination

All list endpoints return paginated results. Pass page and per_page query parameters.

{
  "data": [...],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 312,
    "pages": 7
  }
}

Portcos

Portfolio company records — one row per portco your firm manages.

curl -H "Authorization: Bearer rfk_live_..." \
  "https://rollforgeops.ai/api/v1/portcos?per_page=100"

{
  "id": 1,
  "name": "Blue Ridge HVAC",
  "vertical": "HVAC",
  "geography": "Atlanta, GA",
  "tech_count": 18,
  "annual_revenue": 4200000,
  "ebitda": 630000,
  "close_date": "2024-03-15",
  "status": "active",
  "created_at": "2024-03-15T09:00:00Z",
  "updated_at": "2025-05-01T14:22:00Z"
}

KPIs

Vendor spend and operational KPI data per portco and category.

curl -H "Authorization: Bearer rfk_live_..." \
  "https://rollforgeops.ai/api/v1/kpis?portco_id=1"

Operating Scores

Composite 0–100 operating scores per portco, computed daily across 8 weighted modules: Pricing, Workforce, Memberships, Marketing, Conversion, Integration, Compliance, Financial.

curl -H "Authorization: Bearer rfk_live_..." \
  "https://rollforgeops.ai/api/v1/scores?since=2025-01-01"

{
  "portco_id": 1,
  "portco_name": "Blue Ridge HVAC",
  "overall_score": 82.4,
  "grade": "B",
  "trend_30d": +3.1,
  "trend_90d": +7.8,
  "top_strength": "Strong close rate (68% vs 60% P50)",
  "top_risk": "3 expired licenses (compliance −22pts)",
  "computed_at": "2025-05-05T02:00:00Z"
}

Pipeline

Acquisition pipeline deals at all stages: sourced → screening → LOI → diligence → closing → closed_won / passed.

curl -H "Authorization: Bearer rfk_live_..." \
  "https://rollforgeops.ai/api/v1/pipeline?stage=diligence"

Compliance

Credential records per portco — licenses, insurance policies, bonds, certifications. Filter by status to pull expiring or expired items.

curl -H "Authorization: Bearer rfk_live_..." \
  "https://rollforgeops.ai/api/v1/compliance?status=expired"

Webhooks

Receive real-time events via HTTP POST to any HTTPS endpoint you control. Configure webhooks from the Webhooks dashboard.

Event Reference

{
  "event": "score.recomputed",
  "occurred_at": "2025-05-05T14:22:00Z",
  "data": {
    // event-specific payload
  }
}

Signature Verification

Every delivery includes an X-RollForge-Signature header. Verify it to reject forged requests.

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['x-rollforge-signature'];
  if (!verifySignature(req.body, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  // process event...
  res.status(200).send('OK');
});

import hmac, hashlib

def verify_signature(raw_body: bytes, header: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

Retry Logic

Failed deliveries (non-2xx response or connection timeout) are retried automatically:

After 3 failed attempts the delivery is marked failed. View the full delivery log in your Webhooks dashboard.

Scheduled CSV Exports

Configure recurring dataset exports on an hourly, daily, or weekly schedule. Deliver to Amazon S3 (presigned PUT URL), SFTP, or trigger on-demand downloads. Configure from the Exports dashboard.

Datasets available: portcos, kpis, scores, pipeline, compliance, workforce, memberships.

Incremental sync: Enable to export only rows modified since the last successful run using an updated_at watermark. Ideal for large portcos with high-frequency KPI updates.

Dataset Schemas

portcos

scores

compliance

Snowflake

Use an External Stage pointing at your S3 bucket, then COPY INTO your target table on a schedule.

1. In RollForge, create a daily CSV export for your dataset with destination = S3. Provide a presigned PUT URL for your S3 bucket.
2. In Snowflake, create an external stage on the same S3 bucket.
3. Schedule a Snowflake Task that runs COPY INTO after each export window.

CREATE STAGE rollforge_stage
  URL = 's3://your-bucket/rollforge-exports/'
  CREDENTIALS = (AWS_KEY_ID = '...' AWS_SECRET_KEY = '...');

COPY INTO portcos_raw
  FROM @rollforge_stage/portcos_
  FILE_FORMAT = (TYPE = CSV SKIP_HEADER = 1)
  PATTERN = '.*portcos.*\.csv';

BigQuery

Use BigQuery Data Transfer with an S3 source, or load directly from Cloud Storage if you relay exports there.

1. Configure a daily S3 export in RollForge.
2. Set up a Cloud Storage sync from S3 (AWS CLI or Lambda) to a GCS bucket.
3. Create a BigQuery Data Transfer job from the GCS bucket, scheduled to run daily.

bq load --autodetect --source_format=CSV \
  myproject:rollforge.portcos \
  gs://your-bucket/rollforge-exports/portcos_*.csv

Fivetran

Use Fivetran's REST API connector to pull data from RollForge's REST API v1.

1. In Fivetran, add a new connector → "REST API".
2. Base URL: https://rollforgeops.ai/api/v1
3. Authentication: Header → Authorization: Bearer rfk_live_...
4. Configure endpoints: /portcos, /scores, /compliance, /pipeline
5. Set sync frequency (hourly recommended). Fivetran handles pagination via the meta.page field automatically.

Airbyte

Use Airbyte's HTTP Source (Low-Code CDK or custom connector) to sync from the REST API.

1. In Airbyte, add a new source → "HTTP API" (or build a custom connector).
2. Configure the base URL and authorization header with your API key.
3. Define streams for each endpoint: portcos, kpis, scores, pipeline, compliance.
4. Each stream uses cursor-based incremental sync on the updated_at field.

streams:
  - name: portcos
    primary_key: id
    cursor_field: updated_at
    retriever:
      requester:
        url_base: https://rollforgeops.ai
        path: /api/v1/portcos
        http_method: GET
        authenticator:
          type: ApiKeyAuthenticator
          header: Authorization
          api_token: "Bearer {{ config['api_key'] }}"
      paginator:
        type: DefaultPaginator
        page_size_option:
          inject_into: request_parameter
          field_name: per_page
        pagination_strategy:
          type: PageIncrement
          page_size: 200