Marketplace API Documentation

The Agentic Labs Marketplace API provides programmatic access to the platform's personal data vault, contacts, bookings, address data, AI-powered photo reviews, and credit system. Built on Supabase PostgREST with 160+ canonical data fields across 15 categories.

Key Concepts

• Canonical Schema — 160+ standardized field names across 15 categories. Every data point maps to a single canonical path like identity.first_name.
• Storage Types — synced fields are accessible via API. device fields stay on the user's phone and cannot be read or written remotely.
• Visibility — Each synced field has a per-user visibility setting: hidden, contacts_only, or everyone.
• Consent-Based Access — Business apps declare required fields. Users approve access per-field. API access is gated by consent.

Authentication

All API requests require an API key passed in two headers. The same key is used for both the apikey and Authorization headers.

Required Headers

apikey: your_api_key
Authorization: Bearer your_api_key
Content-Type: application/json

Base URL

https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/

All endpoint paths in this documentation are relative to this base URL unless otherwise noted. Edge Functions use https://ysegezedklvhfkwbttzv.supabase.co/functions/v1/ as their base.

Response Format

All responses are returned as JSON. Successful list queries return arrays. Single-object queries return arrays with one element. Use the Prefer: return=representation header on POST/PATCH to receive the created/updated object.

Canonical Schema Reference

The complete registry of 178 canonical fields organized across 15 categories. Every piece of user data in the platform maps to one of these canonical paths. Plugins, APIs, CSV imports, and business apps all use these keys as the universal data language.

Vault Data

Read and write canonical vault fields for contacts. The vault resolves field paths to their correct storage location (contacts table, contact_profiles table, or vault_data_points table) automatically.

# Read all identity fields for a contact
curl "https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/vault_data_points?contact_id=eq.a1b2c3d4-e5f6-7890-abcd-ef1234567890&category=eq.identity" \
  -H "apikey: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(
  `https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/vault_data_points?contact_id=eq.${contactId}&category=eq.identity`,
  {
    headers: {
      "apikey": API_KEY,
      "Authorization": `Bearer ${API_KEY}`,
    },
  }
);
const data = await res.json();

import requests

headers = {
    "apikey": API_KEY,
    "Authorization": f"Bearer {API_KEY}",
}
resp = requests.get(
    f"https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/vault_data_points?contact_id=eq.{contact_id}&category=eq.identity",
    headers=headers,
)
data = resp.json()

[
  {
    "id": "uuid",
    "contact_id": "a1b2c3d4-...",
    "category": "identity",
    "key": "first_name",
    "value": "John",
    "visibility": "contacts_only",
    "verified": true,
    "source": "scan",
    "created_at": "2026-03-20T14:30:00Z",
    "updated_at": "2026-03-20T14:30:00Z"
  }
]

curl -X POST "https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/vault_data_points" \
  -H "apikey: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: resolution=merge-duplicates,return=representation" \
  -d '{
    "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "category": "property",
    "key": "roof_type",
    "value": "composite shingle",
    "visibility": "contacts_only",
    "source": "import"
  }'

const res = await fetch(
  "https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/vault_data_points",
  {
    method: "POST",
    headers: {
      "apikey": API_KEY,
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      "Prefer": "resolution=merge-duplicates,return=representation",
    },
    body: JSON.stringify({
      contact_id: contactId,
      category: "property",
      key: "roof_type",
      value: "composite shingle",
      visibility: "contacts_only",
      source: "import",
    }),
  }
);

resp = requests.post(
    "https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/vault_data_points",
    headers={
        "apikey": API_KEY,
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
        "Prefer": "resolution=merge-duplicates,return=representation",
    },
    json={
        "contact_id": contact_id,
        "category": "property",
        "key": "roof_type",
        "value": "composite shingle",
        "visibility": "contacts_only",
        "source": "import",
    },
)

Contacts

Manage contact records. Contacts are the core entity in the platform — every user, customer, and service provider is a contact.

curl "https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/contacts?or=(first_name.ilike.*john*,last_name.ilike.*john*,email.ilike.*john*)&deleted_at=is.null&limit=20&order=created_at.desc" \
  -H "apikey: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY"

const q = "john";
const res = await fetch(
  `https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/contacts?or=(first_name.ilike.*${q}*,last_name.ilike.*${q}*,email.ilike.*${q}*)&deleted_at=is.null&limit=20`,
  {
    headers: {
      "apikey": API_KEY,
      "Authorization": `Bearer ${API_KEY}`,
    },
  }
);

Bookings

Create and manage service bookings. Bookings track the lifecycle of a service request from initial request through completion.

curl -X POST "https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/bookings" \
  -H "apikey: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{
    "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "business_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "scheduled_start": "2026-04-15T09:00:00Z",
    "notes": "Replace water heater"
  }'

const res = await fetch(
  "https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/bookings",
  {
    method: "POST",
    headers: {
      "apikey": API_KEY,
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      "Prefer": "return=representation",
    },
    body: JSON.stringify({
      customer_id: "a1b2c3d4-...",
      business_id: "b2c3d4e5-...",
      scheduled_start: "2026-04-15T09:00:00Z",
      notes: "Replace water heater",
    }),
  }
);

Addresses

Search and query the platform's nationwide address database with 63M+ indexed addresses, enriched with property data, voter records, and more.

curl "https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/platform_addresses?address_street=ilike.*Oak*&address_state=eq.TX&limit=10&select=id,address_street,address_city,address_state,address_zip,sqft,bedrooms,bathrooms,roof_type" \
  -H "apikey: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY"

Edge Functions

Serverless functions for AI-powered features like photo review and document scanning.

{
  "extracted_fields": {
    "identity.first_name": "John",
    "identity.last_name": "Smith",
    "contact.address_street": "3231 Running Fawn Dr",
    "document.dl_number": "[REDACTED]",
    "document.dl_expires": "2028-11-15"
  },
  "confidence": 0.95,
  "document_type": "drivers_license"
}

Credits

Query platform credit balances and transaction history. Credits power the platform economy for referrals, canvassing rewards, and business incentives.

curl "https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/credit_transactions?contact_id=eq.a1b2c3d4-e5f6-7890-abcd-ef1234567890&order=created_at.desc&limit=50" \
  -H "apikey: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY"

resp = requests.get(
    f"https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/credit_transactions",
    headers=headers,
    params={
        "contact_id": f"eq.{contact_id}",
        "order": "created_at.desc",
        "limit": "50",
    },
)

MCP Server

The Marketplace MCP server enables AI assistants and external tools to interact with the platform via the Model Context Protocol. Connect your AI assistant, IDE, or automation tool for 2-way data sync.

Installation

# Clone and install
git clone https://github.com/agntc-labs/marketplace.git
cd marketplace/mcp-server
npm install

# Set environment variables
export SUPABASE_URL="https://ysegezedklvhfkwbttzv.supabase.co"
export SUPABASE_SERVICE_KEY="your_service_role_key"

# Run the server
node index.js

Claude Desktop Configuration

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "marketplace": {
      "command": "node",
      "args": ["/path/to/marketplace/mcp-server/index.js"],
      "env": {
        "SUPABASE_URL": "https://ysegezedklvhfkwbttzv.supabase.co",
        "SUPABASE_SERVICE_KEY": "your_service_role_key"
      }
    }
  }
}

Available Tools

Code Examples

Complete working examples for common API workflows.

Read Customer Profile (Multi-Source)

This pattern reads data from both the contacts table and vault_data_points in a single workflow:

const BASE = "https://ysegezedklvhfkwbttzv.supabase.co/rest/v1";
const headers = {
  "apikey": API_KEY,
  "Authorization": `Bearer ${API_KEY}`,
};

async function getFullProfile(contactId) {
  // Fetch contact + vault data in parallel
  const [contact, vault] = await Promise.all([
    fetch(`${BASE}/contacts?id=eq.${contactId}&select=*`, { headers })
      .then(r => r.json()),
    fetch(`${BASE}/vault_data_points?contact_id=eq.${contactId}`, { headers })
      .then(r => r.json()),
  ]);

  // Merge into a unified profile
  const profile = { ...contact[0] };
  for (const point of vault) {
    profile[`${point.category}.${point.key}`] = point.value;
  }
  return profile;
}

import requests
from concurrent.futures import ThreadPoolExecutor

BASE = "https://ysegezedklvhfkwbttzv.supabase.co/rest/v1"
headers = {
    "apikey": API_KEY,
    "Authorization": f"Bearer {API_KEY}",
}

def get_full_profile(contact_id: str) -> dict:
    with ThreadPoolExecutor() as executor:
        contact_fut = executor.submit(
            requests.get,
            f"{BASE}/contacts?id=eq.{contact_id}&select=*",
            headers=headers,
        )
        vault_fut = executor.submit(
            requests.get,
            f"{BASE}/vault_data_points?contact_id=eq.{contact_id}",
            headers=headers,
        )

    contact = contact_fut.result().json()[0]
    vault = vault_fut.result().json()

    profile = {**contact}
    for point in vault:
        profile[f"{point['category']}.{point['key']}"] = point["value"]
    return profile

Batch Update Vault Fields

# Update multiple property fields in a single request
# Note: PostgREST supports bulk insert with arrays
curl -X POST "https://ysegezedklvhfkwbttzv.supabase.co/rest/v1/vault_data_points" \
  -H "apikey: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: resolution=merge-duplicates,return=representation" \
  -d '[
    {"contact_id":"a1b2...","category":"property","key":"roof_type","value":"composite","source":"import"},
    {"contact_id":"a1b2...","category":"property","key":"roof_age_years","value":"3","source":"import"},
    {"contact_id":"a1b2...","category":"property","key":"sqft","value":"2400","source":"import"},
    {"contact_id":"a1b2...","category":"property","key":"bedrooms","value":"4","source":"import"}
  ]'

Rate Limits & Errors

API rate limits and standard error response format.

Rate Limits

HTTP Status Codes

Error Response Format

{
  "code": "PGRST204",
  "details": null,
  "hint": null,
  "message": "Column 'invalid_col' of relation 'contacts' does not exist"
}