# 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

```bash
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:

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

## Spark REST API reference

- **OpenAPI specification:** <https://spark-v8.vercel.app/openapi.json> — every
  public endpoint with operation IDs, typed schemas, and error formats
  compatible with LLM function calling.
- **`GET /api/v1`** — discovery document for the public API.
- **`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 exposes two read-only tools — `spark_get_status` and
`spark_get_api_index` — so MCP clients (Claude, ChatGPT, and others) can query
Spark natively. Example handshake:

```bash
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 serves Markdown when you send
`Accept: text/markdown`. Responses include `Vary: Accept` so caches keep the
variants separate.

## Agent guidance

Read [llms.txt](https://spark-v8.vercel.app/llms.txt) for when-to-use guidance,
and [sitemap.xml](https://spark-v8.vercel.app/sitemap.xml) for the full list of
indexable pages. Questions or integration bugs: make a support request at
[nevetsinc.vercel.app/support](https://nevetsinc.vercel.app/support).

---

[Home](https://spark-v8.vercel.app/) · [About](https://spark-v8.vercel.app/about) · [Contact](https://spark-v8.vercel.app/contact) · [Privacy](https://spark-v8.vercel.app/privacy)