Dynamite Circle Discovery API

openapi: 3.2.0
info:
  contact:
    name: DC Team
    url: https://dc.dynamitecircle.com
  description: 'Programmatic access to your DC membership data — trips, events, profile, announcements, and more. Designed for AI assistants, automation, and personal integrations. > **For ALL active DC members.** Every active DC member is eligible from day one — DC, DC BLACK, and trial accounts alike. ## What this is for


    The DC Member API is for **personal use** — wiring DC into your own AI assistant, scripting personal automations, pulling your own data into your own dashboards. Think "give my Claude/Codex/Cursor access to my DC trips and announcements" or "auto-update my DC trip when I book a flight."


    **It is not for:**


    - Building apps that other DC members log into (use the official DC app)

    - Crawling, scraping, or bulk-exporting member data

    - Building an alternative DC client

    - Public-facing services running on top of the API


    We **augment, we don''t replace** — the API gives you awareness and convenience, then sends you to the app for the real interactions. Human stuff stays in the app: no message content, no DM access, no bulk profile browsing, no discussion threads. **Rate limits are strict on purpose.** They''re sized for personal automation, not application traffic. We''ll loosen them once we see real usage patterns — if you hit a wall, email the DC developer team at **bugs+api@dynamitecircle.com** and we''ll sort you out. ## Connect to Claude & other AI apps (hosted MCP)


    This API is also a hosted MCP server — add it as a connector in Claude, Cursor, ChatGPT, or any MCP-compatible app and your assistant can read and act on your DC data directly. **No install.** When prompted, **sign in with your DC account** (one-click OAuth) — or paste a `dk_` API key. Every endpoint below is exposed as a tool. **Connector URL** (Streamable HTTP): `https://api.dynamitecircle.com/mcp`


    - **Claude (web, Desktop & mobile):** Settings → Connectors → **Add custom connector** → paste the URL → **Connect**, then sign in with your DC account. (Paid Claude plan; on Team/Enterprise an admin may need to approve it first.)

    - **Claude Code:** `claude mcp add --transport http dc https://api.dynamitecircle.com/mcp`

    - **Cursor, ChatGPT & other MCP apps:** add a custom / remote MCP connector pointing at the URL above (Streamable HTTP). Discovery is published at `/.well-known/mcp.json`. **What you can do once connected** — ask in plain language, e.g. "Which DCBKK sessions have I bookmarked?", "Add a trip to Lisbon and show me which DCers will be around", "RSVP me to the next Bangkok meetup", "Summarize the latest announcements." Reads run freely; writes do exactly what the matching endpoint documents. Access is scoped to **you** — the connector only ever sees your own membership data. ## Official client — Agent Skill, CLI, Python library, MCP server


    The fastest way to use this API — and to plug it into Claude Code, Codex CLI, Gemini CLI, Cursor, GitHub Copilot, or Claude Desktop — is the **official DC client**. One self-contained Python file, stdlib only, that ships as **four integrations from the same source**: Agent Skill (auto-discovered via SKILL.md), CLI (`dc …`), Python library (`from dc import DC`), and MCP server (`dc --mcp`, optional `mcp` dep). **Install via PyPI** (easiest):


    ```bash

    pip install dynamitecircle

    dc setup --api-key dk_your_api_key

    dc self-test

    dc profile

    ```


    The package is published on PyPI as `dynamitecircle` — same code as the repo, version-locked to the deployed API.'
  title: DC Member Discovery API
  version: 2.6.11
servers:
- description: Production
  url: https://api.dynamitecircle.com
security:
- ApiKeyAuth: []
tags:
- name: Discovery
paths:
  /profile-match:
    post:
      description: '**AI-powered profile matchmaker.** Match DCers against a natural-language description, or — when `query` is omitted — recommend DCers based on your own profile (chapter, industry, expertise, goals).


        Returns ranked results from a profile-vector search (Gemini embeddings + reranking under the hood). The caller''s LLM synthesizes any narrative on top. Stricter rate limits than the standard CRUD endpoints because of the embedding/rerank cost.


        **Two modes**:

        - **With `query`**: free-form description ("DCers in Lisbon who run SaaS").

        - **Without `query`**: AI builds an implicit query from your profile and returns "DCers you should meet". Useful for cold-start "who should I message this week?" prompts.


        **Optional structured filters** (combine with either mode, all AND-ed):

        - `locationChapterPlaceID` — narrow to DCers whose home / base location is this city. Matched by city rather than place ID, so a city carrying more than one Google place ID is not split. Use for "based in X" queries. Resolve via `GET /places/search`.

        - `locationCurrentPlaceID` — narrow to DCers currently in this place (auto-derived from their last GPS / active trip). Matched by city, so GPS-derived locations count too. Use for "currently in X" / "visiting X" queries.

        - `eventID` — narrow to DCers holding a valid ticket to this event ("DCers attending DCMEX who run logistics"). Refunded / canceled tickets are excluded.

        - `isDCB` — when `true`, narrow to DC BLACK members only.

        - `businessIndustry` — exact match on the DCer''s primary business industry.

        - `minTeamSize` — "at least this size" filter on team headcount (only matches DCers whose team-size visibility is shared with all DCers).

        - `minAnnualRevenue` — "at least this revenue" filter on annual revenue (only matches DCers whose revenue visibility is shared with all DCers).

        - `gender` — exact match on the DCer''s self-reported gender. **Note: Gender is sparsely populated — most DCers leave it blank.** Use this as a "narrow if set" hint rather than a hard requirement; combine with `query` for best results.'
      operationId: post_profile-match
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  results:
                    items:
                      type: object
                    type: array
                    description: Ranked profile matches, highest combined score first
                    properties:
                      score:
                        type: number
                        description: 'Composite ranking score (0-1, higher = better match). When the keyword reranker ran, this is `0.8 * vectorScore + 0.2 * normalizedKeywordScore`. When `skipReranking: true` or the query was empty, this equals `vectorScore`. Use this for ordering — it''s what the API sorted by.'
                      vectorScore:
                        type: number
                        description: Pure vector-similarity score (0-1, higher = closer in embedding space). Derived from the Firestore euclidean distance via `1 / (1 + distance)`. Useful for inspecting raw semantic similarity independent of the keyword overlap.
                      keywordScore:
                        type: number
                        description: Keyword-overlap score from the reranker (uncapped, scale depends on query length). Only present when the reranker ran (i.e. query was a string and `skipReranking` was not set). Useful for debugging why a result ranked where it did.
                      profile:
                        type: object
                        description: Standard profile object (same shape used by `/profile`, `/events/:eventID/attendees`, `/chapters/:cityID`, etc.). Sensitive fields (`annualRevenue`, `teamSize`, `peopleOfInterest`) only populate when the owner shared them with all DCers.
                type: object
          description: Success
        '401':
          description: Unauthorized — missing or invalid API key
        '403':
          description: Forbidden — inactive membership or not eligible
        '429':
          description: Rate limit exceeded
      summary: Match DCers from a description (or recommend if omitted)
      tags:
      - Discovery
      requestBody:
        content:
          application/json:
            schema:
              properties:
                query:
                  type: string
                  description: Free-form description of the DCers you want to find. Omit to get recommendations based on your own profile.
                  example: DCers in Lisbon who run SaaS
                locationChapterPlaceID:
                  type: string
                  description: Optional. Google Place ID — narrows results to DCers based here ("based in X"). Resolve via `GET /places/search`.
                  example: ChIJ-ZRLfIQzMBQR2bAQQ8sZh90
                locationCurrentPlaceID:
                  type: string
                  description: 'Optional. Google Place ID — narrows results to DCers currently here, whether they live there or are visiting. Matched by city rather than by place ID, so it finds DCers whose location came from GPS as well as those who picked a place, and it is not split when a city has more than one Google place ID. Still narrower than a trip: `currentLocation` is only set for DCers sharing location. For a full "who is in <city> right now?" prefer creating a trip via `POST /trips` and reading `GET /trips/:tripID` — the `discovery.fullPool` block lists locals AND visitors during the trip window. Resolve placeIDs via `GET /places/search`.'
                  example: ChIJ82ENKDJgHTERIEjiXbIAAQE
                eventID:
                  type: string
                  description: Optional. DC event ID — narrows results to DCers with a valid ticket (RSVP yes/maybe or paid). Pair with `query` for "DCers attending X who do Y".
                  example: BbZlk82DNQFbV4HT2nJo
                isDCB:
                  type: boolean
                  description: Optional. When `true`, narrows results to DC BLACK members only.
                  example: true
                businessIndustry:
                  type: string
                  description: 'Optional. Exact-match filter on the DCer''s primary business industry. Allowed values: `SaaS & Tech`, `Marketing Agency`, `Productized Services`, `Ecommerce & Amazon`, `Courses and Info Products`, `Affiliate, Content Creation, or Ad Revenue`, `Professional Services & Industry Specific Consulting`, `Real Estate and Investing`, `Coaching`, `Other`.'
                  example: SaaS & Tech
                minTeamSize:
                  type: string
                  description: Optional. "At least this team size" filter — matches DCers whose team-size bucket is >= this value, ordered as `None < 1-2 < 3-5 < 6-9 < 10-14 < 15-19 < 20-34 < 35-49 < 50-74 < 75-99 < 100+`. `Prefer not to say` also exists in the bucket vocabulary but is treated as "unknown" and always filtered out. Only DCers who set their team-size visibility to "all DCers" are matched; the rest are excluded silently.
                  example: 10-14
                minAnnualRevenue:
                  type: string
                  description: Optional. "At least this revenue" filter on annual revenue. Pass any revenue label (e.g. `$1M+`, `$250K+`, `$100K+`); the filter parses to a number and matches DCers at-or-above. Only DCers who set their revenue visibility to "all DCers" are matched; the rest are excluded silently.
                  example: $1M+
                gender:
                  type: string
                  description: 'Optional. Exact-match filter on the DCer''s self-reported gender. Allowed values: `Man`, `Woman`, `Non-binary`, `Prefer not to say`. **Note: Gender is sparsely populated — most DCers leave it blank** — combine with `query` rather than relying on this alone.'
                  example: Woman
                skipReranking:
                  type: boolean
                  description: Optional. When `true`, skip the keyword reranker and return results in raw vector-similarity order. Useful when the query is fuzzy/semantic (where exact keyword overlap would add noise) or when comparing reranked vs raw ordering.
                  example: false
                limit:
                  type: number
                  description: Max results (1-50, default 50). Hard cap at 50 — match is expensive; narrow with filters instead of paginating.
              type: object
        required: true
components:
  securitySchemes:
    ApiKeyAuth:
      bearerFormat: dk_<userID>_<random>
      description: 'Your DC Member API key. Generate one from the user menu inside the DC member area (admin/tester access required). Send it as `Authorization: Bearer dk_your_api_key`.'
      scheme: bearer
      type: http