Dynamite Circle Search 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 Search API
  version: 2.6.11
servers:
- description: Production
  url: https://api.dynamitecircle.com
security:
- ApiKeyAuth: []
tags:
- name: Search
paths:
  /search:
    get:
      description: 'Cross-resource search across profiles, rooms, messages (incl. private DMs + group DMs you''re in), events, and chapters in one round trip. Returns the top-N matches per resource, grouped by resource.


        Use this when you don''t yet know which resource carries the answer — agents typically call this first, then drill into a specific `GET /search/` for more depth on a single bucket. There''s no page param: when you hit the per-resource limit and want more, switch to the per-resource endpoint for that one.


        The events slice has a baked-in forward-looking default (events ending in the last 30 days or later, and currently enabled) — this matches the in-app "Search across DC" surface. Use `GET /search/events` directly to look further back in time.


        **Query syntax (`q=`):** plain words match with prefix + typo tolerance. Wrap a phrase in double quotes to require an exact ordered match — e.g. `q="remote work"`. AND/OR/NOT/parentheses are NOT parsed in `q=` — use the structured filter params below for boolean composition.'
      operationId: get_search
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  profiles:
                    type: object
                    description: Profile matches (shape per `GET /search/profiles`).
                    properties:
                      hits:
                        items:
                          type: object
                        type: array
                        description: Matching profile records.
                      total:
                        type: number
                        description: Total matches.
                  rooms:
                    type: object
                    description: Room matches.
                    properties:
                      hits:
                        items:
                          type: object
                        type: array
                        description: Matching room records.
                      total:
                        type: number
                        description: Total matches.
                  messages:
                    type: object
                    description: Message matches — privacy-gated to your own access. Includes private DMs + group DMs you are a member of; public-room messages from any room.
                    properties:
                      hits:
                        items:
                          type: object
                        type: array
                        description: Matching message records.
                      total:
                        type: number
                        description: Total matches.
                  events:
                    type: object
                    description: Event matches — baked-in forward-looking filter (last 30 days or later, enabled events).
                    properties:
                      hits:
                        items:
                          type: object
                        type: array
                        description: Matching event records.
                      total:
                        type: number
                        description: Total matches.
                  chapters:
                    type: object
                    description: Chapter matches.
                    properties:
                      hits:
                        items:
                          type: object
                        type: array
                        description: Matching chapter records.
                      total:
                        type: number
                        description: Total matches.
                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: Cross-resource omni-search
      tags:
      - Search
      parameters:
      - description: Search text (1-500 chars). Required.
        example: remote work
        in: query
        name: q
        required: true
        schema:
          type: string
      - description: Per-resource hits cap (1-25). The same cap applies to each resource — so `limit=5` returns up to 5 profiles + 5 rooms + 5 messages + 5 events + 5 chapters.
        in: query
        name: limit
        required: false
        schema:
          default: '5'
          type: number
      - description: Scope each resource to this DCer's content — their profile, messages they authored, rooms they created, events they host, chapters they belong to. The @-mention pattern from the in-app search.
        in: query
        name: userID
        required: false
        schema:
          type: string
  /search/profiles:
    get:
      description: 'Full-text search across DCer profiles — headlines, bios, business descriptions, expertise, hobbies, etc. Returns matching profile records with privacy gates applied (hidden + guest profiles filtered out).


        For structured/AI-driven matchmaking ("DCers in Lisbon who run SaaS"), prefer `POST /profile-match` — it has a richer ranking pipeline and filters. This endpoint is the plain full-text fallback.


        **Query syntax (`q=`):** plain words match with prefix + typo tolerance. Wrap a phrase in double quotes to require an exact ordered match — e.g. `q="remote work"`. AND/OR/NOT/parentheses are NOT parsed in `q=` — use the structured filter params below for boolean composition.'
      operationId: get_search_profiles
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  hits:
                    items:
                      type: object
                    type: array
                    description: Matching records — shape depends on the resource being searched.
                  total:
                    type: number
                    description: Visible records returned on this page after access checks.
                  page:
                    type: number
                    description: Current page (1-indexed).
                  hasMore:
                    type: boolean
                    description: True when this visible page is full and more backend results may be available; advance with `?page=<current+1>`.
                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: Search profiles
      tags:
      - Search
      parameters:
      - description: Search text. Required.
        example: SaaS founder
        in: query
        name: q
        required: true
        schema:
          type: string
      - description: Max hits per page (1-50).
        in: query
        name: limit
        required: false
        schema:
          default: '20'
          type: number
      - description: 1-indexed page number.
        in: query
        name: page
        required: false
        schema:
          default: '1'
          type: number
  /search/rooms:
    get:
      description: 'Search rooms by name, description, and topic. Returns rooms that match the query AND that you have access to (subscribed-or-browsable; private rooms / DMs / group DMs you''re NOT a member of are filtered out).


        **Query syntax (`q=`):** plain words match with prefix + typo tolerance. Wrap a phrase in double quotes to require an exact ordered match — e.g. `q="remote work"`. AND/OR/NOT/parentheses are NOT parsed in `q=` — use the structured filter params below for boolean composition.'
      operationId: get_search_rooms
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  hits:
                    items:
                      type: object
                    type: array
                    description: Matching records — shape depends on the resource being searched.
                  total:
                    type: number
                    description: Visible records returned on this page after access checks.
                  page:
                    type: number
                    description: Current page (1-indexed).
                  hasMore:
                    type: boolean
                    description: True when this visible page is full and more backend results may be available; advance with `?page=<current+1>`.
                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: Search rooms
      tags:
      - Search
      parameters:
      - description: Search text. Required unless `userID` is given.
        example: outsourcing
        in: query
        name: q
        required: false
        schema:
          type: string
      - description: 'Room type filter. Allowed: `channel`, `dm`, `group`, `discussion`, `quick-question`, `event`.'
        in: query
        name: type
        required: false
        schema:
          type: string
      - description: Scope to rooms created by this DCer.
        in: query
        name: userID
        required: false
        schema:
          type: string
      - description: Max hits per page (1-100).
        in: query
        name: limit
        required: false
        schema:
          default: '20'
          type: number
      - description: 1-indexed page number.
        in: query
        name: page
        required: false
        schema:
          default: '1'
          type: number
  /search/messages:
    get:
      description: 'Search message bodies across every room you can access. **This is the key surface for "catch me up on what was said about X"** — your private DMs, group DMs, and any room you''re a member of are all searchable. Messages from rooms you don''t belong to are filtered out before any results return.


        Scope to one room with `?roomID=` (the room is double-gated against your membership — passing a roomID you''re not in returns 403, not silently-empty results). Scope to one author with `?userID=`. The two compose: `?roomID=&userID=` returns just messages by that author in that one room.


        **Query syntax (`q=`):** plain words match with prefix + typo tolerance. Wrap a phrase in double quotes to require an exact ordered match — e.g. `q="remote work"`. AND/OR/NOT/parentheses are NOT parsed in `q=` — use the structured filter params below for boolean composition.'
      operationId: get_search_messages
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  hits:
                    items:
                      type: object
                    type: array
                    description: Matching records — shape depends on the resource being searched.
                  total:
                    type: number
                    description: Visible records returned on this page after access checks.
                  page:
                    type: number
                    description: Current page (1-indexed).
                  hasMore:
                    type: boolean
                    description: True when this visible page is full and more backend results may be available; advance with `?page=<current+1>`.
                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: Search messages (incl. your private DMs)
      tags:
      - Search
      parameters:
      - description: Search text. Required unless `userID` is given.
        example: hiring in Lisbon
        in: query
        name: q
        required: false
        schema:
          type: string
      - description: Scope to a single room. Must be a room you are a member of — otherwise returns 403. Discover roomIDs via `GET /rooms`, `GET /inbox/unread`, or `trip.roomID` on `GET /trips/:tripID`.
        in: query
        name: roomID
        required: false
        schema:
          type: string
      - description: Scope to messages authored by this DCer.
        in: query
        name: userID
        required: false
        schema:
          type: string
      - description: Max hits per page (1-100).
        in: query
        name: limit
        required: false
        schema:
          default: '20'
          type: number
      - description: 1-indexed page number.
        in: query
        name: page
        required: false
        schema:
          default: '1'
          type: number
  /search/events:
    get:
      description: 'Search enabled DC events by name, description, host, and venue. No default time filter — pass `?since=` or `?until=` (ISO 8601 dates) to constrain. They compose: pass both for an explicit window.


        **Query syntax (`q=`):** plain words match with prefix + typo tolerance. Wrap a phrase in double quotes to require an exact ordered match — e.g. `q="remote work"`. AND/OR/NOT/parentheses are NOT parsed in `q=` — use the structured filter params below for boolean composition.'
      operationId: get_search_events
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  hits:
                    items:
                      type: object
                    type: array
                    description: Matching records — shape depends on the resource being searched.
                  total:
                    type: number
                    description: Visible records returned on this page after access checks.
                  page:
                    type: number
                    description: Current page (1-indexed).
                  hasMore:
                    type: boolean
                    description: True when this visible page is full and more backend results may be available; advance with `?page=<current+1>`.
                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: Search events
      tags:
      - Search
      parameters:
      - description: Search text. Required unless `userID` is given.
        example: DCBKK
        in: query
        name: q
        required: false
        schema:
          type: string
      - description: Scope to events hosted by this DCer.
        in: query
        name: userID
        required: false
        schema:
          type: string
      - description: Events whose chapter city is this Google Place ID.
        in: query
        name: cityID
        required: false
        schema:
          type: string
      - description: ISO 3166-1 alpha-2 country code (e.g. `TH`, `MX`).
        in: query
        name: country
        required: false
        schema:
          type: string
      - description: Events ending on or after this date (ISO 8601).
        in: query
        name: since
        required: false
        schema:
          type: string
      - description: Events starting on or before this date (ISO 8601).
        in: query
        name: until
        required: false
        schema:
          type: string
      - description: Max hits per page (1-100).
        in: query
        name: limit
        required: false
        schema:
          default: '20'
          type: number
      - description: 1-indexed page number.
        in: query
        name: page
        required: false
        schema:
          default: '1'
          type: number
  /search/chapters:
    get:
      description: 'Search DC chapters by city or country name.


        **Query syntax (`q=`):** plain words match with prefix + typo tolerance. Wrap a phrase in double quotes to require an exact ordered match — e.g. `q="remote work"`. AND/OR/NOT/parentheses are NOT parsed in `q=` — use the structured filter params below for boolean composition.'
      operationId: get_search_chapters
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  hits:
                    items:
                      type: object
                    type: array
                    description: Matching records — shape depends on the resource being searched.
                  total:
                    type: number
                    description: Visible records returned on this page after access checks.
                  page:
                    type: number
                    description: Current page (1-indexed).
                  hasMore:
                    type: boolean
                    description: True when this visible page is full and more backend results may be available; advance with `?page=<current+1>`.
                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: Search chapters
      tags:
      - Search
      parameters:
      - description: Search text. Required.
        example: Bangkok
        in: query
        name: q
        required: true
        schema:
          type: string
      - description: Max hits per page (1-100).
        in: query
        name: limit
        required: false
        schema:
          default: '20'
          type: number
      - description: 1-indexed page number.
        in: query
        name: page
        required: false
        schema:
          default: '1'
          type: number
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