API Reference

Complete reference for all API endpoints in the 1 OAK MLS Platform.

Authentication

Methods

Role Hierarchy

member < agent < admin < owner

Higher roles inherit all permissions of lower roles.

Rate Limiting

Public routes use Upstash Redis rate limiting.

Rate limit headers returned:

• X-RateLimit-Limit: Maximum requests allowed
• X-RateLimit-Remaining: Requests remaining
• X-RateLimit-Reset: Unix timestamp when limit resets

Public Routes

Base: /api/public Authentication: None (rate limited by IP)

GET /api/health

Returns service health status.

Response:

{
  "status": "ok",
  "supabase": "connected",
  "typesense": "connected",
  "timestamp": "2026-01-31T12:00:00Z"
}

GET /api/public/stats

Query Parameters:

• workspace_id (required): Workspace identifier

Response:

{
  "total_listings": 2500,
  "active_listings": 1800,
  "workspace_count": 1
}

GET /api/public/areas

Query Parameters:

• workspace_id (required): Workspace identifier

Response:

{
  "areas": [
    {
      "id": "uuid",
      "name": "Miami Beach",
      "slug": "miami-beach",
      "listing_count": 450
    }
  ]
}

GET /api/public/areas/[slug]

Query Parameters:

• workspace_id (required): Workspace identifier
• page (optional): Page number (default: 1)
• per_page (optional): Items per page (default: 24, max: 100)
• sort (optional): Sort field (e.g., list_price, bedrooms)

Response:

{
  "area": {
    "id": "uuid",
    "name": "Miami Beach",
    "slug": "miami-beach"
  },
  "listings": [...],
  "pagination": {
    "page": 1,
    "per_page": 24,
    "total": 450,
    "total_pages": 19
  }
}

POST /api/contact

Rate Limit: auth tier (5 req/min)

Body:

{
  "workspace_id": "uuid",
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "555-123-4567",
  "message": "I'm interested in...",
  "listing_id": "uuid (optional)"
}

Dashboard Routes (Web App)

Base: /api/dashboard Authentication: Supabase session required

User must be authenticated and have workspace membership.

Listings

GET /api/dashboard/listings

Query Parameters:

• mode: picker or management
• property_type: Filter by property type
• status: Filter by status
• min_price, max_price: Price range
• page, per_page: Pagination

Photos

Service Areas

Import Tasks

Members & Invitations

Domains

Settings & Branding

Blog Posts

Post categories: blog, market-report, neighborhood-guide, press, just-sold Post statuses: draft, published, archived

Draft Social Posts

Draft posts are auto-created when features.autoDraftPosts is enabled and listing status changes are detected. Posts target Instagram, Facebook, and LinkedIn.

Automation Outbox

Outbox items are auto-created when features.automations is enabled and listing status changes match configured automation rules. Requires AI Content Generation to be enabled with an API key configured. See Automations Reference for full details.

Media Library

Accepted formats: JPEG, PNG, WebP, HEIC. Categories: hero, listing, blog, branding, general.

Leads

Analytics

AI Content Generation

All AI routes require features.aiContentGeneration to be enabled.

Status Changes

Returns listing transitions like new listings, price changes, status changes (Active→Pending→Closed), and delisted events.

Page-Specific Hero & Video

Supported page slugs: about, contact, listings, blog.

MLS Connection

Landing Pages

Requires features.landingPages to be enabled.

Account & Dashboard Home

Listing Utilities

Sync Management

System Health

Billing

POST /api/billing/checkout

Creates a Stripe Checkout Session for subscribing to a plan. Redirects user to Stripe-hosted checkout.

Rate limit: auth tier (5 req/min)

Body:

{
  "plan": "professional",
  "interval": "year"
}

Response:

{
  "url": "https://checkout.stripe.com/c/pay/..."
}

POST /api/billing/portal

Creates a Stripe Customer Portal session for managing billing.

Rate limit: auth tier (5 req/min)

Response:

{
  "url": "https://billing.stripe.com/p/session/..."
}

GET /api/billing/subscription

Returns the current subscription, access state, AI usage, and available upgrades.

Rate limit: api tier (60 req/min)

Response:

{
  "subscription": {
    "plan": "professional",
    "status": "active",
    "billingInterval": "year",
    "currentPeriodEnd": "2027-02-25T00:00:00Z",
    "cancelAtPeriodEnd": false,
    "isOverride": false,
    "overrideReason": null
  },
  "access": {
    "plan": "professional",
    "status": "active",
    "isActive": true,
    "isPastDue": false,
    "isOverride": false,
    "features": { "maxListings": 5000, "blog": true, "..." : "..." }
  },
  "availableUpgrades": ["prestige"],
  "aiUsageCount": 42,
  "role": "owner"
}

Webhook

Handles: checkout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, invoice.payment_succeeded, invoice.payment_failed

Admin Routes (Admin App)

Base: /api/admin Authentication: Supabase session + workspace membership with minimum role

Workspaces

POST /api/admin/workspaces

Body:

{
  "name": "My Realty",
  "slug": "my-realty",
  "owner_email": "owner@example.com"
}

Workspace Listings

GET /api/admin/workspaces/[id]/listings

Query Parameters:

• property_type: Filter by type
• status: Filter by StandardStatus
• import_task_id: Filter by import task
• page, per_page: Pagination
• sort, order: Sorting

MLS Connection

POST /api/admin/workspaces/[id]/mls

Body:

{
  "base_url": "https://api.bridgedataoutput.com/api/v2/OData",
  "dataset_id": "mfr_reso",
  "access_token": "your-bridge-token"
}

Import Tasks

POST /api/admin/workspaces/[id]/imports

Body:

{
  "name": "Miami Beach Active",
  "filter": "City eq 'Miami Beach' and StandardStatus eq 'Active'",
  "cadence": "hourly",
  "max_records": 500,
  "enabled": true
}

POST /api/admin/workspaces/[id]/imports/[taskId]/run

Body:

{
  "mode": "incremental"  // or "full"
}

Timeout: 300 seconds

Sync Management

Field Mapping

Members & Invitations

Workspace Configuration

Billing Override (Platform Admin)

POST /api/admin/workspaces/[id]/billing

Body:

{
  "is_billing_override": true,
  "plan": "prestige",
  "override_reason": "Charter partner — founding client"
}

AI Routes (Web App)

Base: /api/dashboard/ai Authentication: Supabase session + workspace membership

Requires workspace.settings.features.aiContentGeneration to be enabled.

Full route list is documented in the AI Content Generation section under Dashboard Routes.

POST /api/dashboard/ai/generate-blocks

Generates website content blocks (hero text, value props, about sections) using AI with automatic Fair Housing compliance checks.

Body:

{
  "agentName": "Jane Smith",
  "brokerage": "Luxury Homes Realty",
  "serviceAreas": ["Miami Beach", "Coral Gables"],
  "specialty": "luxury waterfront properties"
}

Response:

{
  "blocks": {
    "hero": "Your Luxury Miami Waterfront Expert",
    "valueProps": ["..."],
    "about": "..."
  },
  "fairHousingCheck": {
    "passed": true,
    "flaggedTerms": []
  },
  "usage": {
    "inputTokens": 250,
    "outputTokens": 800,
    "costCents": 2
  }
}

GET /api/dashboard/ai/usage

Response:

{
  "currentMonth": {
    "totalGenerations": 15,
    "totalInputTokens": 3750,
    "totalOutputTokens": 12000,
    "totalCostCents": 30
  },
  "tier": "free",
  "tierLimit": 50,
  "remaining": 35
}

Invitation Routes (Web App)

Base: /api/invitations Authentication: Supabase session required

Workspace Discovery (Web App)

Base: /api/workspaces Authentication: Supabase session required

Cron Routes (Admin App)

Base: /api/cron Authentication: CRON_SECRET header

GET /api/cron/sync

Headers:

Authorization: Bearer {CRON_SECRET}

Runs syncs for all enabled import tasks based on their cadence settings.

Response:

{
  "results": [
    {
      "workspace": "lainey-levin",
      "import_task_id": "uuid",
      "status": "success",
      "records_fetched": 50
    }
  ]
}

Auth Routes (Admin App)

Common Response Formats

Success Response

{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 24,
    "total": 150
  }
}

Error Response

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": { ... }
}

Pagination

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 24,
    "total": 150,
    "total_pages": 7,
    "has_next": true,
    "has_prev": false
  }
}

HTTP Status Codes

Related Documentation

• Bridge API - Bridge Interactive API reference
• Custom Domains - Custom domain setup
• Runbook - Operations runbook
• Troubleshooting - Common issues