Dynamite Circle Trips 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 Trips API
  version: 2.6.11
servers:
- description: Production
  url: https://api.dynamitecircle.com
security:
- ApiKeyAuth: []
tags:
- name: Trips
paths:
  /trips:
    get:
      description: 'Returns your upcoming trips by default. Add `?past=true` to include past trips.


        **For "who should I meet on this trip?"** fetch `GET /trips/:tripID` (or the discovery-only `GET /trips/:tripID/discovery`) — both return the ranked top-10 DCers + AI-written summaries + the full pool of locals and visitors in town during the trip window. The list response below does NOT include the discovery block (lazy by design — discovery is a much heavier payload).'
      operationId: get_trips
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  trips:
                    items:
                      type: object
                    type: array
                    description: Array of your trips. List responses ship a lean trip shape — `discovery` is always `null` on list reads to keep payloads small; fetch `GET /trips/:tripID` to get the enriched discovery block.
                    properties:
                      tripID:
                        type: string
                        description: Trip ID
                      note:
                        type: string
                        description: Trip note/description
                      location:
                        type: object
                        description: Trip destination (city-level)
                        properties:
                          placeID:
                            type: string
                            description: Google Place ID
                          name:
                            type: string
                            description: Place name
                          city:
                            type: string
                            description: City
                          country:
                            type: string
                            description: Country
                          countryCode:
                            type: string
                            description: ISO country code
                          region:
                            type: string
                            description: Region / state / prefecture
                          regionCode:
                            type: string
                            description: Region short code
                          description:
                            type: string
                            description: Friendly display string
                          lat:
                            type: number
                            description: Latitude
                          lon:
                            type: number
                            description: Longitude
                          latLon:
                            type: string
                            description: '"lat,lon" string'
                          locHash:
                            type: string
                            description: Geohash for the location
                          utcOffsetMins:
                            type: number
                            description: UTC offset in minutes
                      startDate:
                        type: string
                        description: Start date (ISO 8601)
                      endDate:
                        type: string
                        description: End date (ISO 8601)
                      eventID:
                        type: string
                        description: DC event ID if this trip was created from an event, otherwise `null`.
                      createdAt:
                        type: string
                        description: Trip created-at (ISO 8601).
                      updatedAt:
                        type: string
                        description: Trip updated-at (ISO 8601).
                      points:
                        items:
                          type: object
                        type: array
                        description: Embedded venue/idea notes (up to 20 per trip). Each `{ note, place }` where `place` is the full resolved Google Place object or `null` for note-only items.
                      roomID:
                        type: string
                        description: Linked auto-created chat room for this trip, or `null` if no room was provisioned.
                      discovery:
                        type: object
                        description: Always `null` on list reads. Fetch `GET /trips/:tripID` for the enriched discovery block.
                  nextCursor:
                    type: string
                    description: Cursor for the next page, or `null` if no more trips.
                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: List your trips
      tags:
      - Trips
      parameters:
      - description: Include past trips.
        in: query
        name: past
        required: false
        schema:
          default: 'false'
          type: boolean
      - description: Max results (1-100).
        in: query
        name: limit
        required: false
        schema:
          default: '50'
          type: number
      - description: Cursor from a previous response's `nextCursor`. Pass to fetch the next page.
        in: query
        name: cursor
        required: false
        schema:
          default: ''
          type: string
    post:
      description: 'Create a new trip. Provide exactly one of `placeID` or `eventID` — the server resolves the location (city, country, country code) automatically. Use `GET /places/search` to find a placeID by city/country name first, or pass an `eventID` from `/events` to create a trip to that event''s city.


        **Trip points** (optional `points` array, up to 20 per trip): each item is `{ note: string (max 280 chars), noteHTML?: string, placeID?: string }`. The optional `placeID` is resolved against Google Places at write time and the full Place object (city, country, lat/lon, name, etc.) is stored on the trip — so reads don''t do any lookups. `noteHTML` preserves the same rich text field the web trip editor stores for formatted notes, links, and mentions; `note` remains the required plain-text fallback. Notes without a placeID are valid ("remember to book a coworking space"). Pass an unknown / expired Google placeID → 400 with a clear error.'
      operationId: post_trips
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  trip:
                    type: object
                    description: The created trip
                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: Create a trip
      tags:
      - Trips
      requestBody:
        content:
          application/json:
            schema:
              properties:
                startDate:
                  type: string
                  description: Start date (ISO 8601)
                  example: '2026-05-01'
                endDate:
                  type: string
                  description: End date (ISO 8601)
                  example: '2026-05-10'
                placeID:
                  type: string
                  description: Google Place ID for the destination. Look one up via `GET /places/search`. **Pass exactly one of `placeID` or `eventID`** — sending both rejects with 400.
                  example: ChIJ-ZRLfIQzMBQR2bAQQ8sZh90
                eventID:
                  type: string
                  description: DC event ID. Server uses the event's city placeID. **Pass exactly one of `placeID` or `eventID`** — sending both rejects with 400.
                  example: sWnllj1DW2jLMZ1n2KWB
                note:
                  type: string
                  description: Trip note
                  example: Co-working week
                points:
                  items:
                    type: object
                  type: array
                  description: 'Optional. Up to 20 trip points (venues / ideas / notes). Each item: `{ note: string (max 280 chars), noteHTML?: string, placeID?: string }`. The optional `placeID` is resolved against Google Places at write time. Notes without a place are valid.'
                  example:
                  - note: Coffee at Wheelys
                    noteHTML: <p>Coffee at <strong>Wheelys</strong></p>
                    placeID: ChIJ-ZRLfIQzMBQR2bAQQ8sZh90
                  - note: Book coworking space
              type: object
              required:
              - startDate
              - endDate
        required: true
  /trips/{tripID}:
    patch:
      description: 'Update one or more fields on an existing trip. Only include the fields you want to change. To change destination, provide either `placeID` or `eventID` and the full location will be re-resolved.


        **Trip points**: passing `points` replaces the entire array (it''s not a patch within the array). Up to 20 items, same shape as `POST /trips`: `{ note: string (max 280 chars), noteHTML?: string, placeID?: string }`. To clear all points, pass `points: []`.'
      operationId: patch_trips__tripID
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  trip:
                    type: object
                    description: The updated trip
                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: Update a trip
      tags:
      - Trips
      parameters:
      - description: The trip ID to update
        example: abc123
        in: path
        name: tripID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                startDate:
                  type: string
                  description: New start date (ISO 8601)
                endDate:
                  type: string
                  description: New end date (ISO 8601)
                placeID:
                  type: string
                  description: New destination — Google Place ID
                eventID:
                  type: string
                  description: New destination — DC event ID (uses event's city). Pass `null` to unlink without changing the location.
                note:
                  type: string
                  description: Updated note
                points:
                  items:
                    type: object
                  type: array
                  description: Optional. Replace the entire `points` array (not a patch within). Up to 20 items, same shape as `POST /trips`. Pass `[]` to clear all points.
              type: object
        required: true
    delete:
      description: Permanently delete one of your trips. Removes the trip doc and its linked chat room (`trip.roomID`). The destination chapter's upcoming-trip count is recomputed in the background. **Owner-only** — you can only delete trips you created. The action is irreversible; deleted trips don't go to a trash collection.
      operationId: delete_trips__tripID
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    type: boolean
                    description: Always `true` on success. The endpoint returns 404 if the trip never existed or 403 if you don't own it.
                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: Delete a trip
      tags:
      - Trips
      parameters:
      - description: The trip ID to delete
        example: abc123
        in: path
        name: tripID
        required: true
        schema:
          type: string
    get:
      description: 'Single-trip read with the full payload. **This is the canonical endpoint for "who should I meet on this trip?"** — the response embeds a complete `discovery` block (ranked top-10 picks with AI summaries, the full pool of locals + visitors, events in town, and date-overlapping trips). If you only want the discovery block without the trip body, use `GET /trips/:tripID/discovery`.


        **Key discovery fields agents almost always want:**

        - `discovery.people` — **ranked top-10 DCers to meet** on this trip, each carrying `score` (higher = better match), mini `profile` (userID, userName, displayName, photo, headline), `reason` (`local` / `visiting` / `event-attendee`), `overlapDays`, `detail`. Sourced from a vector-search + business-context ranking, not just date overlap.

        - `discovery.whyToMeet` — **AI-written "why you should meet them" paragraph** for each of the top-10, keyed by userID, each `{ text, generatedAt }`. The most useful AI signal in the whole trip product — agents should surface this verbatim when introducing a match.

        - `discovery.fullPool` — every visible DCer travelling or local during the trip window (typically 5–10× larger than `/trips/overlaps`, which only returns date-window matches). Same row shape as `people` but no `score`.

        - `discovery.overlappingTrips` — other DCers travelling at the same time/place, each with mini profile attached so no second fetch is needed. This is the same data that `/trips/overlaps` returns, embedded here for convenience.

        - `discovery.events` — events in the destination city during the trip window.

        - `discovery.generatedAt` — when the discovery cache was last refreshed.


        **Also included:** `points` — up to 20 venue/idea notes with optional Google Place data, plus a linked `roomID` for the auto-created trip coordination room.


        Hidden + guest profiles are filtered out from all discovery lists. The `discovery` block is `null` for newly-created trips until the background sync task runs (~seconds — call `POST /trips/:tripID/refresh` to force-recompute). Open to any authenticated DCer (you can read other DCers'' trips too).'
      operationId: get_trips__tripID
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  trip:
                    type: object
                    description: The full trip including points and the enriched discovery block
                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: Get a single trip
      tags:
      - Trips
      parameters:
      - description: The trip ID
        example: abc123
        in: path
        name: tripID
        required: true
        schema:
          type: string
  /trips/overlaps:
    get:
      description: 'Find other members whose trips overlap with yours by city + date range. **This is a narrow date-window match, NOT the AI-ranked discovery pool.** For the full set of DCers you could meet on a trip — including locals in town and AI-written "why you should meet them" summaries — fetch `GET /trips/:tripID/discovery` (or `GET /trips/:tripID`, which embeds the same `discovery` block). The discovery pool is typically 5–10× larger than `/trips/overlaps` because it includes locals and event attendees in addition to date-overlap visitors, and it carries ranked top-10 picks with AI summaries that this endpoint does not.


        Use `/trips/overlaps` for the simple "who is travelling here at the same time as me" question. Use `/trips/:tripID/discovery` for "who should I meet on this trip?".'
      operationId: get_trips_overlaps
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  overlaps:
                    items:
                      type: object
                    type: array
                    description: One entry per upcoming trip of yours that has overlapping trips from other DCers
                    properties:
                      trip:
                        type: object
                        description: Your trip
                        properties:
                          tripID:
                            type: string
                            description: Trip ID
                          eventID:
                            type: string
                            description: Linked event ID (null if not linked)
                          note:
                            type: string
                            description: Trip note
                          startDate:
                            type: string
                            description: Start date (ISO 8601)
                          endDate:
                            type: string
                            description: End date (ISO 8601)
                          location:
                            type: object
                            description: Trip destination
                            properties:
                              placeID:
                                type: string
                                description: Google Place ID
                              name:
                                type: string
                                description: Display name
                              city:
                                type: string
                                description: City
                              country:
                                type: string
                                description: Country
                              countryCode:
                                type: string
                                description: ISO country code
                      matches:
                        items:
                          type: object
                        type: array
                        description: Other members whose trips overlap with yours in this destination
                        properties:
                          member:
                            type: object
                            description: The other member's profile (same shape as `/profile` for other DCers)
                            properties:
                              userID:
                                type: string
                                description: Member ID
                              userName:
                                type: string
                                description: Username (handle)
                              displayName:
                                type: string
                                description: Display name
                              photo:
                                type: string
                                description: Profile photo URL
                              profileURL:
                                type: string
                                description: Profile URL on DC
                              headline:
                                type: string
                                description: Profile headline
                              businessIndustry:
                                type: string
                                description: Business industry
                              joinedDate:
                                type: string
                                description: Join date (YYYY-MM-DD)
                          trip:
                            type: object
                            description: Their overlapping trip
                            properties:
                              tripID:
                                type: string
                                description: Their trip ID
                              note:
                                type: string
                                description: Their trip note (if shared)
                              startDate:
                                type: string
                                description: Their start date (ISO 8601)
                              endDate:
                                type: string
                                description: Their end date (ISO 8601)
                          overlapDays:
                            type: number
                            description: Number of overlapping days between your trip and theirs
                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: Find overlapping trips
      tags:
      - Trips
      parameters:
      - description: Max trips to check (1-20)
        in: query
        name: limit
        required: false
        schema:
          default: '10'
          type: number
  /trips/{tripID}/refresh:
    post:
      description: Owner-only sync trigger. Enqueues a deduped background job that recomputes the trip's discovery (overlapping people, events, AI blurbs). Spammy reloads coalesce. Returns 202 Accepted immediately; the cached `discovery` block on the trip doc updates when the job completes.
      operationId: post_trips__tripID_refresh
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  accepted:
                    type: boolean
                    description: Whether the refresh was accepted
                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: Trigger a trip refresh
      tags:
      - Trips
      parameters:
      - description: The trip ID to refresh
        example: abc123
        in: path
        name: tripID
        required: true
        schema:
          type: string
  /trips/{tripID}/discovery:
    get:
      description: 'Discovery-only read for a trip. Returns the same `discovery` block as `GET /trips/:tripID` (people, fullPool, whyToMeet, events, overlappingTrips) without the trip body. Useful for callers that just want "who should I meet on this trip?" — the AI agent gets the ranked top-10 + their `whyToMeet` paragraphs in a single request.


        Use `?include=` to subset the response — comma-separated from `people,fullPool,whyToMeet,events,overlappingTrips`. Default is all. Common patterns:

        - `?include=people,whyToMeet` — top-10 picks + their AI-written "why you should meet them" paragraphs (keyed by userID, each carrying `{ text, generatedAt }`)

        - `?include=fullPool` — every visible DCer travelling/local during the trip window

        - `?include=events` — just events in the destination city during the trip window


        Open to any authenticated DCer; hidden + guest profiles are filtered out.'
      operationId: get_trips__tripID_discovery
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  discovery:
                    type: object
                    description: The trip's cached discovery block. `null` if the trip has no discovery yet (newly created, sync hasn't run). Filtered to the keys requested in `?include=`.
                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: Get the discovery block for a trip
      tags:
      - Trips
      parameters:
      - description: The trip ID
        example: abc123
        in: path
        name: tripID
        required: true
        schema:
          type: string
      - description: Optional. Comma-separated subset of `people,fullPool,whyToMeet,events,overlappingTrips`. Default = all five.
        example: people,whyToMeet
        in: query
        name: include
        required: false
        schema:
          type: string
  /trips/recent:
    get:
      description: 'Recently added trips across the community — the app''s Locator › New Trips tab. The latest trips by creation time that have not ended yet, newest first, each with its traveller (members with a hidden profile are left out). Your own follows are a subset: filter by `member.userID` against `GET /follows/profiles`.'
      operationId: get_trips_recent
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  trips:
                    items:
                      type: object
                    type: array
                    description: Trips (same shape as `GET /trips` items) plus `member` {userID, displayName, userName, photo, profileURL}.
                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: Recently added trips (community)
      tags:
      - Trips
      parameters:
      - description: Max results (1-100)
        in: query
        name: limit
        required: false
        schema:
          default: '50'
          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