# Jaspor API

Welcome to the Jaspor API. your direct access to Jaspor’s dynamic dataset and intent-driven networking engine on **X.com**.

This API is designed for **builders, founders, and developers** who want to plug Jaspor’s intelligence and network into their own products, dashboards, and workflows. You bring the idea, we provide the **signal, intros, and proof**.

All endpoints are **JSON over HTTPS**, versioned at `/v1/`.\
Authentication is via **API keys** (bearer tokens).

***

### Technical Overview

The Jaspor API is powered by a multi-stage AI Matchmaker Algorithm:

1. Input Data Ingestion
   * User profiles: structured metadata (roles, geos, preferences).
   * Behavioral signals: interaction history (likes, replies, dwell time).
   * Semantic embeddings: public text inputs encoded with multi-model LLMs (SBERT, LLaMA-derived).
2. Feature Normalization & Weighting
   * Normalize features into a shared latent space.
   * Apply **hard constraints** (geo, role, filters) and **soft constraints** (interests, vibe scoring).
   * Reinforcement updates from positive matches and sustained conversations.
3. Candidate Retrieval
   * Approximate nearest neighbor (ANN) search with FAISS/HNSW.
   * Hybrid scoring function:

     $$
     S(u,v) = \alpha \cdot \cos(E\_u, E\_v) + \beta \cdot f\_{\text{compat}}(u,v) - \lambda \cdot \text{penalties}
     $$
4. Ranking & Explainability
   * Cross-encoder re-ranking or lightweight neural ranker on top-K.
   * Gradient-based attribution highlights “why” behind each match.
5. Multi-Model LLM Stack
   * Small LLM: parses intent and entities.
   * Mid-sized LLM: drafts intros and smart DMs.
   * Policy LLM: ensures safety, tone, and disclosure.

***

### Top 10 Endpoints

These 10 endpoints showcase Jaspor’s unique value: intent-based matching, real-time discovery, warm intros, and verifiable social graph data.

#### 1. Create an Intent

**POST** `/v1/intents`

Define who or what you’re looking for. Jaspor interprets your goal and starts building matches instantly.

**Request**

{% code fullWidth="false" %}

```json
{
  "goal": "Find AI founders building in design tools",
  "tags": ["ai", "design", "founders"],
  "geos": ["NA", "EU"],
  "timeframe": "next_30_days",
  "notes": "Prefer early-stage, no agencies"
}
```

{% endcode %}

**Response**

```json
{
  "intent_id": "int_12345",
  "status": "active",
  "created_at": "2025-09-28T12:00:00Z"
}
```

***

#### 2. Get Recommended Matches

**POST** `/v1/match/recommendations`

Retrieve ranked candidates Jaspor thinks you should connect with.

**Request**

```json
{
  "intent_id": "int_12345",
  "limit": 10,
  "diversity": "topic"
}
```

**Response**

```json
{
  "intent_id": "int_12345",
  "results": [
    {
      "candidate_id": "x_7781",
      "handle": "@janedoe",
      "score": 0.94,
      "why": ["Seed-stage founder", "Active on AI/UX threads", "Mutuals: @sarahdev"]
    },
    {
      "candidate_id": "x_9912",
      "handle": "@founderAI",
      "score": 0.88,
      "why": ["Recently launched AI design plugin"]
    }
  ]
}
```

***

#### 3. Explain a Match

**GET** `/v1/matches/:id`

Fetch Jaspor’s “why” behind a particular match.

**Response**

```json
{
  "match_id": "match_abc789",
  "candidate": "@janedoe",
  "reasoning": [
    "Active AI founder in design tools",
    "Mutual followers with @you",
    "Engaged with similar content in the past 7 days"
  ],
  "score": 0.94
}
```

***

#### 4. Create a Warm Intro

**POST** `/v1/intros`

Spin up a Jaspor-crafted group DM with the perfect opener.

**Request**

```json
{
  "intent_id": "int_12345",
  "candidate_ids": ["x_7781","x_9912"],
  "platform": "x",
  "opener_style": "friendly",
  "cc_requester": true
}
```

**Response**

```json
{
  "intro_id": "intro_4567",
  "status": "draft",
  "suggested_opener": "Hey all — given your shared focus on AI/UX design tools, thought it made sense to connect you."
}
```

***

#### 5. Send an Intro

**POST** `/v1/intros/:id/send`

Finalize and send the group DM on X.

**Response**

```json
{
  "intro_id": "intro_4567",
  "status": "sent",
  "message_url": "https://x.com/messages/1234"
}
```

***

#### 6. Smart DM Draft

**POST** `/v1/prompts/message`

Generate a context-aware opener for a candidate based on their latest X activity.

**Request**

```json
{
  "candidate_id": "x_7781",
  "tone": "concise",
  "context": "They just shipped an AI Figma plugin",
  "goal": "Explore collab opportunities"
}
```

**Response**

```json
{
  "draft": "Congrats on the Figma plugin launch 🚀 Curious how you're thinking about design-to-compliance workflows."
}
```

***

#### 7. Auto-Circle Creation

**POST** `/v1/circles`

Create a curated “mastermind” group from intent + network data.

**Request**

```json
{
  "name": "AI Founders – NYC",
  "seed_intent_id": "int_12345",
  "membership": { "size": 8, "diversity": "geo" },
  "platform": "telegram"
}
```

**Response**

```json
{
  "circle_id": "circle_9099",
  "members": ["@janedoe","@founderAI","@sarahdev"],
  "kickoff_message": "Welcome! This group is curated around AI founders in NYC."
}
```

***

#### 8. On-Chain Proof of Intro

**POST** `/v1/onchain/intros/:id/proof`

Generate a Solana transaction proving an intro occurred.

**Response**

```json
{
  "intro_id": "intro_4567",
  "tx_base64": "AAAA...",
  "required_signers": ["7XhP9...abc"],
  "expires_at": "2025-10-01T00:00:00Z"
}
```

***

#### 9. Reputation & Badges

**GET** `/v1/onchain/reputation/:wallet`

Fetch Jaspor’s verifiable reputation graph (NFT badges, scores).

**Response**

```json
{
  "wallet": "7XhP9...abc",
  "badges": [
    { "type": "SuperConnector", "minted_at": "2025-09-20T00:00:00Z" },
    { "type": "Top AI Founder", "minted_at": "2025-09-25T00:00:00Z" }
  ],
  "score": 87
}
```

***

#### 10. Real-Time Opportunity Radar

**GET** `/v1/radar/opportunities`

Surface trending conversations and people on X that align with your intent.

**Response**

```json
{
  "intent_id": "int_12345",
  "opportunities": [
    {
      "thread_url": "https://x.com/someone/status/123",
      "summary": "Discussion on AI design tools blowing up",
      "recommended_action": "Engage with @janedoe and @uxAI"
    },
    {
      "thread_url": "https://x.com/other/status/456",
      "summary": "Seed investors sharing interest in AI productivity apps"
    }
  ]
}
```

***

### Usage Notes

* **Rate limits**: 100 requests/minute per key.
* **Auth**: `Authorization: Bearer <api_key>`.
* **Idempotency**: Use `Idempotency-Key` headers for POST requests.
* **Errors**: Standardized JSON:

```json
{ "code": "invalid_request", "message": "Intent not found" }
```
