Cubbie API

Build integrations that feed Cubbie, extend Cubbie, and distribute Cubbie-powered partner surfaces without replacing the Cubbie dashboard.

Dashboard-first API strategy

Cubbie APIs are designed to make the Cubbie workspace more useful. Use the API to ingest stack data, automate partner and vendor operations, send signed events, and deep-link users back into Cubbie for comparison, redemption, renewal, and procurement workflows.

API Surfaces

Buyer stack ingestion

Send subscriptions, usage, seat, renewal, and spend signals into Cubbie so the Cubbie dashboard remains the source of truth.

Advisor + renewal outputs

Trigger analyses and read recommendation summaries for notifications, while deep-linking users back into Cubbie for decisions.

Partner-program distribution

Install Cubbie-powered hosted pages, widgets, and custom-domain surfaces without hiding that Cubbie powers the perks experience.

Vendor + partner webhooks

Subscribe systems to signed events such as redemptions, orders, payouts, referrals, and account updates.

Vendor-admin integrations

Read seats, active users, and plan tier that Cubbie syncs directly from 500+ vendors' own admin APIs, plus bank-level spend via Plaid and directory signal from Google Workspace or Okta. Browse the full list at /integrations.

What We Intentionally Do Not Expose

Cubbie does not provide an unrestricted public API to clone the entire catalog, deals marketplace, rankings, or recommendation experience off-platform. Partner surfaces return Cubbie-hosted URLs, embeds, scripts, and attribution-safe JSON where appropriate, with Cubbie branding and links back to the workspace.

Current Launch Surface

The developer platform is intentionally split by use case: public v1 REST for stack ingestion and Cubbie workspace workflows, partner-program APIs for perks distribution, and vendor webhook tooling for event automation.

Surface	Route	Status	What It Does
Public v1 REST	`/api/v1/*`	Available	API-key authenticated buyer stack, advisor, renewal, vendor-admin, and partner-program discovery. Cubbie Points endpoints use separate ck_ tokens.
OpenAPI contract	`/api/v1/openapi.json`	Available	Machine-readable OpenAPI 3.1 schema for the public v1 REST surface.
Partner programs	`/api/partner-programs/*`	Available	Dashboard-created perks programs with hosted pages, embeds, custom domains, public JSON, referrals, and click tracking. Server-side callers should always use the URLs from `urls` on their own perks domain (for example perks.yourcompany.com). Requests to www.cubbie.com from servers may be challenged and fail.
Vendor webhooks	`/api/vendor/webhooks/*`	Dashboard authenticated	Self-serve vendor endpoint registration, signed deliveries, retries, delivery logs, and secret rotation.
OAuth client credentials	`/api/oauth/token`	Infrastructure ready	Server-to-server token issuance exists for approved clients; public app registration is not exposed yet.

Authentication

Public v1 stack, advisor, renewal, vendor-admin, and partner-program endpoints require a cb_live_... API key. You can create one from your Buyer Dashboard under the "API Keys" section. Cubbie Points endpoints use separate ck_... credit tokens, and vendor webhooks are managed inside the authenticated vendor dashboard.

Getting an API Key

Scroll to the "API Keys" section and click "Create New Key."
Copy the key immediately -- it is shown only once.

Authenticating Requests

Pass the key in the Authorization header:

Authorization: Bearer cb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys follow the format cb_live_ followed by 32 hex characters. Keep your keys secret and never commit them to source control.

Scopes

API keys are scope-limited. Create the narrowest key possible for each integration.

Scope	Purpose
`subscriptions:read`	Read the buyer organization's Cubbie stack registry.
`subscriptions:write`	Create, update, delete, or bulk import stack registry records.
`usage:write`	Send utilization, seat, and activity signals into Cubbie.
`renewals:read`	Read upcoming renewal windows for notifications and deep links.
`advisor:read`	Read current Cubbie advisor recommendations.
`advisor:write`	Trigger Cubbie advisor analyses.
`partner_programs:read`	Read partner-program surfaces, URLs, install snippets, custom domains, content assets, and referrals.
`partner_programs:write`	Create and update partner programs, attach custom domains, and publish content assets.
`webhooks:read`	Reserved for a future release -- webhook endpoints are currently managed from the vendor dashboard.
`webhooks:write`	Reserved for a future release -- webhook endpoints are currently managed from the vendor dashboard.
`vendor_admin:read`	Read vendor-admin connections, seat and usage signals, and rightsizing recommendations.
`catalog:read`	Search the Cubbie software catalog and read product details, attributes, and categories.
`offers:read`	Read publicly visible offers and pricing for catalog products.
`commerce:propose`	Propose orders that a human in the organization must approve before any payment occurs. Agents can never execute a charge.
`commerce:execute`	Capped autopilot: orders inside the key's per-order, monthly, and category caps skip the human approval step (fully audited). Payment is still completed by a human -- agents never charge a card.
`vendor:offers:read`	Read the vendor organization's own offers and their status.
`vendor:orders:read`	Read orders placed against the vendor organization's offers.

Base URLs

Surface	Base
Public v1 REST	`https://cubbie.com/api/v1`
Partner-program public surfaces	`https://cubbie.com/api/partner-programs/public/:slug`
Vendor webhook management	`https://cubbie.com/api/vendor/webhooks`
OAuth token issuance	`https://cubbie.com/api/oauth/token`

All endpoints return JSON with the shape { "ok": true, "data": ... } on success or { "ok": false, "error": { "message": "..." } } on failure.

Partner Programs

Partner programs are the API-backed perks surfaces companies create from Cubbie to power pages like perks.example.com, dashboard embeds, and curated sponsorship panels. The Cubbie dashboard remains the setup workspace: partners create the program, select perks, configure branding, add allowed embed origins, and connect custom domains.

The public API exposes installable outputs for those programs: hosted page URLs, iframe URLs, script snippets, and attribution-safe JSON URLs. This gives partners distribution without turning Cubbie into an invisible white-label catalog.

Endpoint	Purpose
`POST /api/v1/partner-programs`	Create a Cubbie-powered perks, referral, or hybrid partner program.
`GET /api/v1/partner-programs/:id`	Read one program's full configuration, surface URLs, and embed snippets.
`PATCH /api/v1/partner-programs/:id`	Update branding, audience copy, access mode, embedded layout, and curated selection rules.
`GET /api/v1/partner-programs/:id/domains`	List connected custom domains with verification state and DNS records.
`POST /api/v1/partner-programs/:id/domains`	Attach a custom perks subdomain and return the DNS verification instructions.
`GET /api/v1/partner-programs/:id/assets`	List the FAQs, announcements, benefits, and resources on the partner surface.
`POST /api/v1/partner-programs/:id/assets`	Publish FAQs, announcements, benefits, and resources into the partner surface.
`GET /api/v1/partner-programs/:id/referrals`	Read partner referral leads captured by hosted pages and embeds.

Worked request and response examples for the read endpoints are included in the Endpoints reference below.

Vendor Admin API

Vendor-admin endpoints expose what Cubbie pulls from the admin APIs of the vendors you connect from the dashboard: connection metadata, the latest seat, usage, and billing snapshot per vendor, and the rightsizing recommendations Cubbie computes from those signals. All three endpoints are read-only and require a cb_live_... API key with the vendor_admin:read scope. Credentials for connected vendors are never returned.

Endpoint	Purpose
`GET /api/v1/vendor-admin/connections`	List connected vendor-admin integrations with sync status. Metadata only.
`GET /api/v1/vendor-admin/signals`	Latest seat, usage, and billing snapshot per vendor. Filter with `vendor_slug`; cap with `limit`.
`GET /api/v1/vendor-admin/recommendations`	Rightsizing recommendations with action filtering applied (dismissed hidden, snoozed hidden until expiry, accepted flagged).

Vendor Webhooks

Vendors can register webhook endpoints from the vendor dashboard to receive signed event deliveries. Cubbie signs each delivery with HMAC-SHA256 and sends X-Cubbie-Signature, X-Cubbie-Timestamp, and X-Cubbie-Event-Id headers.

Failed deliveries retry after 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours. After repeated failures, endpoints are temporarily disabled to protect both systems.

Supported vendor events

deal.created
deal.redeemed
deal.expired
order.completed
order.refunded
subscription.cancelled
subscription.renewed
payout.released
payout.failed
review.received
vendor.account_updated

AI Agents and MCP

Cubbie is agent-native. Any MCP client (Claude, ChatGPT, Cursor, or a custom procurement agent) can connect to the Cubbie MCP server and search the catalog, compare products, read the organization's stack and spend, pull decision evidence, and propose purchases.

https://cubbie.com/api/mcp

Anonymous connections get the public catalog tools (search_catalog, get_product_details, compare_products). Passing an API key as Authorization: Bearer cb_live_... unlocks the org-scoped tools (get_my_stack, get_my_spend, add_to_stack, get_product_intelligence, propose_order), gated by the same scopes as the REST API.

Purchases are propose-only

An agent can never execute a charge on Cubbie. propose_order (and POST /api/v1/commerce/orders) computes the price server-side from the offer, creates a pending order, and routes it to the organization's approvals inbox. A human approves and completes payment. Agent keys can additionally carry a per-order cap, a monthly cap, and a category allowlist, enforced when the agent proposes AND re-checked when a human approves. The commerce:propose scope is never granted by default.

Machine discovery: https://cubbie.com/llms.txt summarizes all agent-facing interfaces and the rules agents are asked to follow.

Agent Recipes

Recipes for building a procurement agent on the Cubbie MCP server or the REST API. Agents are propose-only by default; capped autopilot (commerce:execute) auto-approves below-cap orders, but a human always completes payment.

Recipe: renewal watchdog

Poll GET /api/v1/renewals/upcoming (scope renewals:read), research alternatives with search_catalog, get_product_details, and get_product_intelligence, then propose a replacement or a renegotiation with propose_order before the renewal date. Every proposal lands in the approvals inbox.

renewals = GET /api/v1/renewals/upcoming?days=45
for renewal in renewals:
  candidates = search_catalog(renewal.category)
  evidence = get_product_intelligence(top_candidate)
  propose_order(offer, note="replace or renegotiate " + renewal.product)
# every proposal -> approvals inbox

Recipe: stack gap filler

Read the organization's stack with get_my_stack, use get_product_intelligence to find category gaps, shortlist candidates with compare_products, and file a propose_order with a note explaining the gap for the human approver.

Connect with OAuth

MCP clients can also connect via OAuth 2.1 (dynamic client registration + PKCE). The client discovers everything from /.well-known/oauth-authorization-server. The consent screen grants scoped access to one buyer organization and mints a revocable API key. commerce:execute can never be granted via OAuth. Spending caps must be configured in the dashboard key manager.

OpenAPI

Use the OpenAPI schema to generate typed clients, validate requests in tests, or import the API into tools like Postman and Scalar.

https://cubbie.com/api/v1/openapi.json

Prefer a ready-to-import collection? Use https://cubbie.com/api/v1/postman.json.

API Explorer

Test public v1 calls from your browser. Keys stay in this page state and are not stored.

RequestAPI Key

GET /api/v1/health

Endpoints

GET/api/v1/health

Health check. No authentication required.

Example Request

curl https://cubbie.com/api/v1/health

Example Response

{
  "ok": true,
  "data": {
    "status": "ok",
    "version": "1.0.0",
    "timestamp": "2026-03-29T12:00:00.000Z"
  }
}

GET/api/v1/openapi.json

OpenAPI 3.1 contract for the public v1 API. No authentication required.

Example Request

curl https://cubbie.com/api/v1/openapi.json

Example Response

{
  "openapi": "3.1.0",
  "info": {
    "title": "Cubbie Public API",
    "version": "1.0.0"
  }
}

GET/api/v1/subscriptions

List all subscriptions for your organization, sorted by most recently updated.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/subscriptions

Example Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "vendor_name": "Slack",
        "product_name": "Slack Business+",
        "source": "integration",
        "annualized_spend_cents": 1440000,
        "renewal_date": "2027-01-15",
        "owner_name": "Dana Ops",
        "owner_email": "[email protected]",
        "status": "active",
        "notes": null,
        "created_at": "2026-03-29T12:00:00.000Z",
        "updated_at": "2026-04-02T09:15:00.000Z"
      }
    ]
  }
}

POST/api/v1/subscriptions

Add a subscription to your stack registry.

Example Request

curl -X POST \
  -H "Authorization: Bearer cb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"vendor_name":"Slack","product_name":"Slack Business+","annualized_spend_cents":1440000,"renewal_date":"2027-01-15"}' \
  https://cubbie.com/api/v1/subscriptions

Example Response

{
  "ok": true,
  "data": {
    "id": "uuid",
    "vendor_name": "Slack",
    "product_name": "Slack Business+",
    "source": "integration",
    "annualized_spend_cents": 1440000,
    "renewal_date": "2027-01-15",
    "owner_name": null,
    "owner_email": null,
    "status": "active",
    "notes": null,
    "created_at": "2026-03-29T12:00:00.000Z"
  }
}

GET/api/v1/subscriptions/:id

Retrieve a single subscription by its ID.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/subscriptions/UUID

Example Response

{
  "ok": true,
  "data": {
    "id": "uuid",
    "vendor_name": "Slack",
    "product_name": "Slack Business+",
    "source": "integration",
    "annualized_spend_cents": 1440000,
    "renewal_date": "2027-01-15",
    "owner_name": "Dana Ops",
    "owner_email": "[email protected]",
    "status": "active",
    "notes": null,
    "created_at": "2026-03-29T12:00:00.000Z",
    "updated_at": "2026-04-02T09:15:00.000Z"
  }
}

PATCH/api/v1/subscriptions/:id

Update fields on an existing subscription.

Example Request

curl -X PATCH \
  -H "Authorization: Bearer cb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"annualized_spend_cents":1600000}' \
  https://cubbie.com/api/v1/subscriptions/UUID

Example Response

{
  "ok": true,
  "data": {
    "id": "uuid",
    "vendor_name": "Slack",
    "product_name": "Slack Business+",
    "source": "integration",
    "annualized_spend_cents": 1600000,
    "renewal_date": "2027-01-15",
    "owner_name": "Dana Ops",
    "owner_email": "[email protected]",
    "status": "active",
    "notes": null,
    "created_at": "2026-03-29T12:00:00.000Z",
    "updated_at": "2026-05-12T08:00:00.000Z"
  }
}

DELETE/api/v1/subscriptions/:id

Delete a subscription from your stack registry.

Example Request

curl -X DELETE \
  -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/subscriptions/UUID

Example Response

{
  "ok": true,
  "data": { "deleted": true }
}

POST/api/v1/subscriptions/bulk

Bulk import up to 500 subscriptions at once.

Example Request

curl -X POST \
  -H "Authorization: Bearer cb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"vendor_name":"Slack","product_name":"Slack Business+","annualized_spend_cents":1440000}]}' \
  https://cubbie.com/api/v1/subscriptions/bulk

Example Response

{
  "ok": true,
  "data": { "created": 1, "failed": 0, "errors": [] }
}

POST/api/v1/advisor/analyze

Trigger a full stack analysis for your organization. Returns gap analysis, benchmarks, and recommendations.

Example Request

curl -X POST \
  -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/advisor/analyze

Example Response

{
  "ok": true,
  "data": {
    "overallScore": 72,
    "totalBenchmarked": 18,
    "covered": 11,
    "missing": 7,
    "gaps": [...],
    "strengths": [...],
    "topPriorityActions": [...],
    "estimatedAnnualSavingsCents": 240000,
    "id": "uuid",
    "recommendations": [...]
  }
}

GET/api/v1/advisor/recommendations

Retrieve current recommendations. Supports optional query params: status, priority.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/advisor/recommendations

Example Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "buyer_org_id": "uuid",
        "gap_analysis_id": "uuid",
        "category_slug": "project-management",
        "category_name": "Project Management",
        "recommendation_type": "missing_essential",
        "priority": "high",
        "headline": "Add a project management tool",
        "rationale": "...",
        "impact_summary": "...",
        "estimated_roi": "...",
        "recommended_products": [...],
        "benchmark_data": { ... },
        "status": "active",
        "dismissed_at": null,
        "acted_on_at": null,
        "created_at": "2026-05-01T17:32:00.000Z",
        "updated_at": "2026-05-01T17:32:00.000Z"
      }
    ]
  }
}

POST/api/v1/usage

Report usage data for a subscription (active users, licensed seats, utilization).

Example Request

curl -X POST \
  -H "Authorization: Bearer cb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"subscription_id":"UUID","active_users":42,"total_licensed_seats":50,"utilization_pct":84}' \
  https://cubbie.com/api/v1/usage

Example Response

{
  "ok": true,
  "data": {
    "id": "uuid",
    "created_at": "2026-03-29T12:00:00.000Z"
  }
}

GET/api/v1/renewals/upcoming

Renewal calendar: upcoming subscription renewals in a configurable window. Sorted ascending so the earliest-due rows surface first.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  "https://cubbie.com/api/v1/renewals/upcoming?days=90&status=active&includePast=false"

Example Response

{
  "ok": true,
  "data": {
    "window": {
      "startsAt": "2026-05-08T00:00:00.000Z",
      "endsAt": "2026-08-06T23:59:59.999Z",
      "days": 90,
      "includePast": false
    },
    "items": [
      {
        "id": "uuid",
        "vendor_name": "Acme",
        "product_name": "Acme Pro",
        "renewal_date": "2026-06-01",
        "days_until_renewal": 24,
        "annualized_spend_cents": 1200000,
        "owner_name": "Dana Ops",
        "owner_email": "[email protected]",
        "status": "active",
        "source": "sso",
        "notes": null
      }
    ],
    "totals": { "count": 1, "total_annualized_spend_cents": 1200000 }
  }
}

GET/api/v1/partner-programs

List Cubbie-powered partner program surfaces: hosted page URLs, embed URLs, script snippets, JSON URLs, state, and perk counts.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/partner-programs

Example Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "50Pros Agency Perks",
        "slug": "50pros-agency-perks",
        "state": "active",
        "visibility": "public",
        "program_type": "perks",
        "access_mode": "open",
        "perk_count": 24,
        "urls": {
          "hostedPageUrl": "https://perks.50pros.com",
          "embedWidgetUrl": "https://perks.50pros.com/embed/perks/50pros-agency-perks",
          "jsonApiUrl": "https://perks.50pros.com/api/partner-programs/public/50pros-agency-perks",
          "scriptEmbedUrl": "https://perks.50pros.com/api/embed/v/v1/embed.js?slug=50pros-agency-perks"
        },
        "embed": {
          "iframe": "<iframe src=...></iframe>",
          "script": "<script async src=...></script>"
        },
        "updated_at": "2026-05-12T08:00:00.000Z"
      }
    ]
  }
}

GET/api/v1/partner-programs/:id

Retrieve one partner program's full configuration, surface URLs, and embed snippets.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/partner-programs/UUID

Example Response

{
  "ok": true,
  "data": {
    "item": {
      "id": "uuid",
      "name": "50Pros Agency Perks",
      "slug": "50pros-agency-perks",
      "headline": "Software perks for your agency network",
      "subheadline": "...",
      "description": "...",
      "audience_label": "Agencies",
      "primary_cta_label": "View perk",
      "state": "active",
      "visibility": "public",
      "program_type": "perks",
      "access_mode": "open",
      "allowed_email_domains": [],
      "analytics_enabled": true,
      "member_portal_enabled": false,
      "referral_leads_enabled": false,
      "script_embed_enabled": true,
      "brand_config": { ... },
      "selection_config": { ... },
      "embed_config": { ... },
      "perk_count": 24,
      "urls": {
        "hostedPageUrl": "https://perks.50pros.com",
        "embedWidgetUrl": "https://perks.50pros.com/embed/perks/50pros-agency-perks",
        "jsonApiUrl": "https://perks.50pros.com/api/partner-programs/public/50pros-agency-perks",
        "scriptEmbedUrl": "https://perks.50pros.com/api/embed/v/v1/embed.js?slug=50pros-agency-perks"
      },
      "embed": {
        "iframe": "<iframe src=...></iframe>",
        "script": "<script async src=...></script>"
      },
      "created_at": "2026-04-01T10:00:00.000Z",
      "updated_at": "2026-05-12T08:00:00.000Z"
    }
  }
}

GET/api/v1/partner-programs/:id/domains

List the program's custom perks domains with verification state, DNS records, and provider status.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/partner-programs/UUID/domains

Example Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "programId": "uuid",
        "hostname": "perks.50pros.com",
        "apexName": "50pros.com",
        "status": "verified",
        "isPrimary": true,
        "verified": true,
        "misconfigured": false,
        "configuredBy": "CNAME",
        "statusMessage": "...",
        "verificationChallenges": [],
        "dnsRecords": [
          {
            "type": "CNAME",
            "hostname": "perks",
            "value": "cname.vercel-dns.com",
            "purpose": "routing"
          }
        ],
        "lastCheckedAt": "2026-05-12T08:00:00.000Z",
        "verifiedAt": "2026-04-02T11:30:00.000Z",
        "createdBy": "uuid",
        "createdAt": "2026-04-01T10:05:00.000Z",
        "updatedAt": "2026-05-12T08:00:00.000Z"
      }
    ],
    "provider": { "configured": true, "label": "Vercel" }
  }
}

GET/api/v1/partner-programs/:id/assets

List the program's content assets: FAQs, announcements, benefits, and resources.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/partner-programs/UUID/assets

Example Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "programId": "uuid",
        "kind": "faq",
        "title": "How do I redeem a perk?",
        "body": "...",
        "ctaLabel": "Open perks page",
        "ctaUrl": "https://perks.50pros.com",
        "sortOrder": 0,
        "isPublished": true,
        "createdBy": "uuid",
        "createdAt": "2026-04-01T10:05:00.000Z",
        "updatedAt": "2026-04-01T10:05:00.000Z"
      }
    ]
  }
}

GET/api/v1/vendor-admin/connections

List your vendor-admin connections. Returns connection metadata only -- credentials are never returned. Requires the vendor_admin:read scope.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/vendor-admin/connections

Example Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "vendor_slug": "slack",
        "vendor_label": "Slack",
        "status": "connected",
        "external_account_id": "T0123ABCD",
        "scopes": ["admin.users:read"],
        "last_sync_at": "2026-05-12T06:00:00.000Z",
        "last_sync_status": "ok",
        "last_sync_error": null,
        "created_at": "2026-04-01T10:00:00.000Z",
        "updated_at": "2026-05-12T06:00:00.000Z"
      }
    ]
  }
}

GET/api/v1/vendor-admin/signals

Latest seat, usage, and billing snapshot per connected vendor. Optional query params: vendor_slug (restrict to one vendor) and limit (default 100, max 500). Requires the vendor_admin:read scope.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  "https://cubbie.com/api/v1/vendor-admin/signals?vendor_slug=slack&limit=50"

Example Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "vendor_slug": "slack",
        "vendor_label": "Slack",
        "plan_tier": "Business+",
        "total_licensed_seats": 50,
        "active_user_count": 42,
        "dormant_user_count": 8,
        "measurement_window_days": 30,
        "per_seat_cost_cents": 1800,
        "annual_spend_cents": 1080000,
        "renewal_date": "2027-01-15",
        "account_manager_email": null,
        "account_manager_name": null,
        "raw_payload": { ... },
        "observed_at": "2026-05-12T06:00:00.000Z"
      }
    ]
  }
}

GET/api/v1/vendor-admin/recommendations

Current rightsizing recommendations computed from connected vendor signals, sorted by priority then estimated savings. Action filtering is applied: dismissed recommendations are hidden, snoozed ones are hidden until the snooze expires, and accepted ones return with action set. Requires the vendor_admin:read scope.

Example Request

curl -H "Authorization: Bearer cb_live_xxxx" \
  https://cubbie.com/api/v1/vendor-admin/recommendations

Example Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "vendor_slug": "slack",
        "vendor_label": "Slack",
        "kind": "downsize_seats",
        "priority": 4,
        "headline": "Reclaim 6 dormant Slack seats",
        "body": "...",
        "estimated_annual_savings_cents": 129600,
        "details": { ... },
        "details_hash": "3f9a...",
        "action": null
      }
    ]
  }
}

GET/api/v1/credits/balance

Cubbie Points wallet: current balance, pending credits awaiting reward fulfillment, and lifetime totals.

Example Request

curl -H "Authorization: Bearer ck_xxxx" \
  https://cubbie.com/api/v1/credits/balance

Example Response

{
  "ok": true,
  "data": {
    "buyer_org_id": "uuid",
    "available_cents": 12500,
    "pending_cents": 3400,
    "lifetime_earned_cents": 38900,
    "lifetime_redeemed_cents": 0,
    "updated_at": "2026-05-01T17:32:00.000Z"
  }
}

GET/api/v1/credits/ledger

Cubbie Points ledger: append-only history of every credit issued, redeemed, reversed, expired, or adjusted. Returns the most recent entries, newest first; limit accepts 1-200 (default 50). There is no cursor-based pagination. kind is one of issue_pending, issue_available, redeem, reverse, expire, adjustment; state is pending, posted, or voided.

Example Request

curl -H "Authorization: Bearer ck_xxxx" \
  "https://cubbie.com/api/v1/credits/ledger?limit=50"

Example Response

{
  "ok": true,
  "data": {
    "buyer_org_id": "uuid",
    "entries": [
      {
        "id": "uuid",
        "kind": "issue_available",
        "state": "posted",
        "amount_cents": 1200,
        "note": "Marketplace order credit",
        "created_at": "2026-05-01T17:32:00.000Z",
        "posted_at": "2026-05-01T17:32:00.000Z",
        "expires_at": null
      }
    ]
  }
}

Error Handling

Errors return a non-2xx status code and a JSON body with the error details:

{
  "ok": false,
  "error": {
    "message": "Unauthorized"
  }
}

An optional error.details field is included when extra context is available, for example field-level validation errors on 400 responses. It is omitted on 5xx responses.

Status	Meaning
`400`	Invalid request body or parameters
`401`	Missing or invalid API key
`403`	Valid key but insufficient permissions
`404`	Resource not found
`429`	Rate limit exceeded
`500`	Internal server error

Rate Limits

Default public v1 limits are 10 requests per second, 600 requests per minute, and 25,000 requests per day per API key. When a limit is exceeded, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying. Higher quotas are available on request -- email [email protected] with your use case.

SDKs

REST is the stable public interface today. JavaScript, TypeScript, Python, Ruby, Go, PHP, and Java can all use the same HTTP API now; official packaged SDKs should be generated from the OpenAPI contract as the public developer platform matures. If you need an official package ahead of public release, email [email protected].

JavaScript / TypeScript quick start

const response = await fetch("https://cubbie.com/api/v1/subscriptions", {
  headers: {
    Authorization: `Bearer ${process.env.CUBBIE_API_KEY}`
  }
});

if (!response.ok) {
  throw new Error(await response.text());
}

console.log(await response.json());

Python quick start

import os
import requests

response = requests.get(
    "https://cubbie.com/api/v1/subscriptions",
    headers={"Authorization": f"Bearer {os.environ['CUBBIE_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Ruby quick start

require "json"
require "net/http"
require "uri"

uri = URI("https://cubbie.com/api/v1/subscriptions")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch('CUBBIE_API_KEY')}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

raise response.body unless response.is_a?(Net::HTTPSuccess)
puts JSON.parse(response.body)

Language	Status
Node.js / TypeScript	REST available now; official SDK planned
Python	REST available now; official SDK planned
Ruby	REST available now; official SDK planned
Go / PHP / Java	REST available now; official SDK planned
HTTP (any client)	Available now