Spark Developer Portal

Spark exposes a small, public, read-only API so developers and AI agents can integrate programmatically: check service status, discover the API surface, and call Spark tools through the Model Context Protocol (MCP). Member data (profiles, matches, messages, calls) is never public; it requires an authenticated member session inside the Spark app.

Spark API quickstart

curl https://spark-v8.vercel.app/api/v1
curl https://spark-v8.vercel.app/api/v1/status

Both endpoints return JSON and require no authentication. Errors are always JSON:

{ "error": { "code": "not_found", "message": "...", "hint": "..." } }

Spark REST API reference

OpenAPI specification: https://spark-v8.vercel.app/openapi.json - the machine-readable description of every public endpoint, with operation IDs, typed schemas, and error formats compatible with LLM function calling.

Public endpoints: GET /api/v1 (discovery document) and GET /api/v1/status (liveness, name, and version). Unknown API paths return a structured JSON 404; unsupported methods return a JSON 405.

Authentication

The public API (/api/v1/*) and the MCP endpoint require no authentication and no API key. Member functionality (profiles, matches, messages, calls) is not part of the public API; it is only available inside the Spark app after signing in, using session tokens issued by Supabase Auth (email/password and supported OAuth providers). There is no public way to act on behalf of a member.

Rate limits

The advertised policy is 60 requests per 60 seconds per client. Every API response carries RFC RateLimit headers - RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds until the window resets) - so agents can self-throttle in real time. Responses also include a Link header pointing at the OpenAPI spec (rel="service-desc") and this portal (rel="help"). If the limit is exceeded the API returns 429 with a Retry-After header and a JSON error body with code: "rate_limited".

Webhooks

Spark does not currently offer public webhooks. The public surface is read-only; poll GET /api/v1/status (respecting the rate limit above) if you need to monitor availability.

Spark MCP server (for AI agents)

Spark ships a Model Context Protocol server over Streamable HTTP at POST /api/mcp, discoverable via /.well-known/mcp. It speaks JSON-RPC 2.0 and currently exposes two read-only tools, spark_get_status and spark_get_api_index, so agents from Claude, ChatGPT, and other MCP clients can check Spark natively. Example handshake:

curl -X POST https://spark-v8.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

Markdown content negotiation

Every content page on this site (including this one) serves Markdown when you send Accept: text/markdown. Responses include Vary: Accept so caches keep the variants separate.

Agent guidance

Read llms.txt for when-to-use guidance aimed at AI agents, and sitemap.xml for the full list of indexable pages. Questions or integration bugs: make a support request at nevetsinc.vercel.app/support.