API Integration Guide

Connect FlatRate Pro to Any Platform

Premium GearGenius plans include a unified API that works with ChatGPT, Claude, MCP servers, Zapier, and any custom application. This guide covers connecting your preferred platform to FlatRate Pro using per-user Connect Tokens.

Supported Platforms

What you'll get

• Per-user auth via Connect Token (no API key sharing)
• 12 endpoints covering profile, jobs, notes, tools, timer, DTC lookup
• Voice Agent parity: everything the voice agent can do, the API can do
• Real-time sync with your FlatRate Pro data

Prerequisites

• A FlatRate Pro account (sign in at https://geargenius.ai)
• Firebase project deployed with Functions and Hosting for this repo
• Deployed Cloud Function: gptActionsHttp and Hosting rewrite for /api/gpt/**

1) Create your Connect Token

1. Open Connect GPT.
2. Sign in.
3. Click "Create token". Copy it immediately.
4. You can revoke the token later on the same page.

2) Available API Endpoints

All endpoints require the X-User-Token header (except /health).

Core Endpoints

Job Management

Tools & Utilities

Voice Agent Parity (Notes, Tools, Timer)

3) Platform Setup Guides

Option A – ChatGPT Custom GPT Action

In ChatGPT → Create a GPT → Configure → Actions:

1. API Base URL: https://geargenius.ai (or your Firebase Hosting domain)
2. Import OpenAPI schema:
   • URL: https://geargenius.ai/.well-known/frp-gpt-openapi.json
3. Authentication: API Key, Header name: X-User-Token, leave value blank
4. Users paste their token when first using the GPT

Option B – ChatGPT Connector (Teams & Enterprise)

1. Open ChatGPT workspace → Connectors → Add Connector
2. Paste manifest URL: https://geargenius.ai/.well-known/frp-connector-manifest.json
3. Leave credential field blank so each user pastes their own token
4. The connector shows FlatRate Pro metadata, categories, and privacy links

Option C – Claude Projects (Anthropic)

1. Create a Connect Token at Connect GPT (label: "claude")
2. In Claude Project settings, add an API integration
3. Configure HTTP requests with:
   • Base URL: https://geargenius.ai/api/gpt
   • Header: X-User-Token: <your-token>
4. Claude can now call any endpoint

Option D – MCP Server (Model Context Protocol)

1. Create a Connect Token (label: "mcp")
2. Configure your MCP server with tools pointing to our endpoints:

{
  "baseUrl": "https://geargenius.ai/api/gpt",
  "headers": { "X-User-Token": "<your-token>" }
}

3. Map endpoints to MCP tools (profile, jobs, timer, etc.)

Option E – Zapier / Make / n8n

1. Create a Connect Token (label: "zapier" or "make")
2. Use the Webhooks by Zapier or HTTP module
3. Configure:
   • URL: https://geargenius.ai/api/gpt/user/jobs/recent
   • Headers: X-User-Token: <your-token>
4. Trigger on schedule or connect to other apps

Option F – LangChain / AI Agents

1. Create a Connect Token (label: "agent")
2. Configure API tool with requests library:

import requests

headers = {"X-User-Token": "your-token"}
response = requests.get(
    "https://geargenius.ai/api/gpt/user/profile",
    headers=headers
)

3. Wrap endpoints as LangChain tools

Option G – Custom REST Integration

Use any HTTP client with the X-User-Token header:

curl -H "X-User-Token: YOUR_TOKEN" \
  https://geargenius.ai/api/gpt/user/stats

curl -X POST -H "X-User-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jobName":"Oil change","actualHours":0.5}' \
  https://geargenius.ai/api/gpt/user/jobs

Recommended System Instructions

Copy and paste these instructions into your Custom GPT "Instructions" field or your Agent's system prompt to ensure it uses the tools correctly.

4) Configure Authentication (per-user)

Use a header-based API key:

• Type: API Key
• Auth Type: Custom (or Bearer – see note below)
• Custom header name: X-User-Token
• API Key value:
  • Leave blank in the builder if you want each user to paste their own token at first use (recommended)
  • For private testing only, you can paste a token; clear it before sharing the GPT

5) Test the connection

From a terminal (replace TOKEN and HOST):

# Health
curl -sS -H "X-User-Token: TOKEN" https://<HOST>/api/gpt/health | jq

# Profile summary
curl -sS -H "X-User-Token: TOKEN" https://<HOST>/api/gpt/user/profile | jq

# Recent jobs
curl -sS -H "X-User-Token: TOKEN" "https://<HOST>/api/gpt/user/jobs/recent?limit=3" | jq

# Quick stats (today, week, or month)
curl -sS -H "X-User-Token: TOKEN" "https://<HOST>/api/gpt/user/stats?range=week" | jq

# Create a job
curl -sS -H "Content-Type: application/json" -H "X-User-Token: TOKEN" \
  -d '{"jobName":"Brake pad swap","category":"Brakes","flatRateHours":1.5,"actualHours":1.2}' \
  https://<HOST>/api/gpt/user/jobs | jq

# Get time estimate
curl -sS -H "Content-Type: application/json" -H "X-User-Token: TOKEN" \
  -d '{"jobDescription":"Replace water pump on 2018 Honda Accord"}' \
  https://<HOST>/api/gpt/user/estimate | jq

# DTC lookup
curl -sS -H "Content-Type: application/json" -H "X-User-Token: TOKEN" \
  -d '{"code":"P0420","make":"Toyota","model":"Camry","year":"2019"}' \
  https://<HOST>/api/gpt/tools/dtc | jq

# Search by vehicle
curl -sS -H "Content-Type: application/json" -H "X-User-Token: TOKEN" \
  -d '{"query":"Honda Civic"}' \
  https://<HOST>/api/gpt/vehicle/lookup | jq

# Save a note
curl -sS -H "Content-Type: application/json" -H "X-User-Token: TOKEN" \
  -d '{"text":"Customer wants synthetic oil only","tags":["customer","oil"]}' \
  https://<HOST>/api/gpt/user/note | jq

# Log a tool purchase
curl -sS -H "Content-Type: application/json" -H "X-User-Token: TOKEN" \
  -d '{"name":"Snap-On 3/8 Ratchet","cost":89.99,"category":"hand tools"}' \
  https://<HOST>/api/gpt/user/tool | jq

# Timer control
curl -sS -H "Content-Type: application/json" -H "X-User-Token: TOKEN" \
  -d '{"action":"start","type":"wrench","jobId":"job123"}' \
  https://<HOST>/api/gpt/user/timer | jq

curl -sS -H "Content-Type: application/json" -H "X-User-Token: TOKEN" \
  -d '{"action":"status"}' \
  https://<HOST>/api/gpt/user/timer | jq

curl -sS -H "Content-Type: application/json" -H "X-User-Token: TOKEN" \
  -d '{"action":"stop"}' \
  https://<HOST>/api/gpt/user/timer | jq

6) Endpoint Details

Refer to the OpenAPI Schema for full details on all available endpoints and request/response formats.

7) Rate limits and safety

• Per-user rate limiting is enforced server-side; excessive calls return HTTP 429.
• Endpoints avoid returning credentials or sensitive PII.
• Job updates are constrained; verified/locked entries cannot be modified.

8) Troubleshooting