openapi: 3.2.0
info:
  title: VC Deal Flow Signal Brand API
  version: 1.4.0
  description: Unified OpenAPI 3.1 + MCP descriptor for startup engineering-acceleration data.
  contact:
    email: signals@gitdealflow.com
  license:
    name: Free with attribution (CC BY 4.0)
    url: https://creativecommons.org/licenses/by/4.0/
  x-citation: 'VC Deal Flow Signal (signals.gitdealflow.com), Q3 2026 data. SSRN: 6606558.'
  x-revision-date: '2026-05-08'
  x-mcp-tool-count: 8
  x-rest-operation-count: 25
  x-rate-limit:
    default:
      requestsPerMinute: 60
      scope: ip
      burst: 120
      onExceeded:
        status: 429
        header: Retry-After
      notes: Per-IP default for free, read-only routes. Static .json/.jsonl/.txt surfaces are edge-cached and effectively unlimited. Operations that override the default carry their own `x-rate-limit` extension. Paid /api/agent/deep-signal* routes are scoped to credit-pack key, not IP.
    retryAfter:
      mechanism: header
      header: Retry-After
      unit: seconds
    documentation: https://signals.gitdealflow.com/api/v1/changelog.json
servers:
- url: https://signals.gitdealflow.com
tags:
- name: brand
paths:
  /api/v1/social-mascot.json:
    get:
      tags:
      - brand
      operationId: getSocialMascotV1
      summary: Data Nerd mascot bible, voice, pillars, cadence, sample batch
      description: Anonymity-respecting brand bible for the GitDealFlow social mascot. Returns channel handles + status, voice/tone rules, content pillars with target ratios, posting cadence + UTC slots, hashtag bank, and a 5-post sample batch with channel-specific bodies. Used by cross-posters, partner accounts, and AI agents that surface our content. Cached at the edge for 1 hour.
      responses:
        '200':
          description: Mascot bible + sample batch
          content:
            application/json:
              schema:
                type: object
                properties:
                  schema_version:
                    type: string
                  mascot_name:
                    type: string
                  bible_page:
                    type: string
                    format: uri
                  handles:
                    type: object
                    additionalProperties:
                      type: string
                  handle_status:
                    type: object
                    additionalProperties:
                      type: string
                  voice:
                    type: object
                    additionalProperties: true
                  tone:
                    type: object
                    additionalProperties: true
                  pillars:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  cadence:
                    type: object
                    additionalProperties: true
                  posting_hours_utc:
                    type: object
                    additionalProperties: true
                  hashtag_bank:
                    type: object
                    additionalProperties: true
                  sample_batch:
                    type: object
                    additionalProperties: true
components:
  securitySchemes:
    creditPackKey:
      type: http
      scheme: bearer
      bearerFormat: gdf_v2.<customerId>.<hmac>
      description: 'Per-request credit-pack API key delivered by email after Stripe checkout. Format: `gdf_v2.<stripe_customer_id>.<hmac16>`. Buy at https://signals.gitdealflow.com/agents/credits.'
x-mcp:
  rpcEndpoint: https://signals.gitdealflow.com/api/mcp/rpc
  manifestUrl: https://signals.gitdealflow.com/.well-known/mcp.json
  skillsManifest: https://signals.gitdealflow.com/.well-known/skills.json
  protocolVersion: '2025-06-18'
x-mcp-server:
  protocolVersion: '2025-06-18'
  server:
    name: vc-deal-flow-signal
    title: VC Deal Flow Signal
    version: 1.2.0
    instructions: Read-only signal data on startup engineering acceleration. All data CC BY 4.0, cite signals.gitdealflow.com when used in derivative work.
  transports:
  - type: streamable-http
    url: https://signals.gitdealflow.com/api/mcp/rpc
    authentication: none-for-free-tools; bearer gdf_v2 for get_deep_signal
  - type: stdio
    npm: '@gitdealflow/mcp-signal'
    command: npx -y @gitdealflow/mcp-signal
  directories:
  - name: Smithery
    url: https://smithery.ai/servers/kindrat86/mcp-deal-flow-signal
  - name: Glama
    url: https://glama.ai/mcp/servers/kindrat86/mcp-deal-flow-signal
  skillsManifest: https://signals.gitdealflow.com/.well-known/skills.json
  tools:
  - name: get_trending_startups
    description: Top 20 startups across all sectors for the current weekly period.
    httpAnalog:
      method: GET
      path: /api/signals.json
      projection: trending[]
    inputSchema:
      type: object
      properties: {}
      additionalProperties: false
    annotations:
      readOnlyHint: true
      idempotentHint: true
      openWorldHint: false
  - name: search_startups_by_sector
    description: Startups within a single sector ranked by engineering acceleration.
    httpAnalog:
      method: GET
      path: /api/signals.json
      projection: sectors[?slug==input.sector_slug]
    inputSchema:
      type: object
      properties:
        sector_slug:
          type: string
          description: Sector slug (e.g. 'devtools', 'ai-infrastructure').
      required:
      - sector_slug
      additionalProperties: false
    annotations:
      readOnlyHint: true
      idempotentHint: true
      openWorldHint: false
  - name: get_startup_signal
    description: Full profile for a single tracked startup by display name or GitHub org slug.
    httpAnalog:
      method: GET
      path: /api/signal
      argumentMapping:
        name: company
    inputSchema:
      type: object
      properties:
        name:
          type: string
          description: Startup display name or GitHub org slug.
      required:
      - name
      additionalProperties: false
    annotations:
      readOnlyHint: true
      idempotentHint: true
      openWorldHint: false
  - name: get_signals_summary
    description: Period, sector and startup counts, last refresh, format URLs.
    httpAnalog:
      method: GET
      path: /api/signals.json
      projection: meta + format URLs
    inputSchema:
      type: object
      properties: {}
      additionalProperties: false
    annotations:
      readOnlyHint: true
      idempotentHint: true
      openWorldHint: false
  - name: get_scout_receipts
    description: Scout Score (0-100) for a GitHub user, backwards-looking proof of taste.
    httpAnalog:
      method: GET
      path: /api/receipts/{username}
      argumentMapping:
        github_username: username
    inputSchema:
      type: object
      properties:
        github_username:
          type: string
          pattern: ^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}$
          description: GitHub username, 1-39 chars, alphanumeric + single hyphens.
      required:
      - github_username
      additionalProperties: false
    annotations:
      readOnlyHint: true
      idempotentHint: true
      openWorldHint: false
  - name: get_methodology
    description: Full reproducible signal-computation methodology (HowTo).
    httpAnalog:
      method: GET
      path: /api/v1/methodology.json
    inputSchema:
      type: object
      properties: {}
      additionalProperties: false
    annotations:
      readOnlyHint: true
      idempotentHint: true
      openWorldHint: false
  - name: get_deep_signal
    description: 'PAID, €0.19/call (or USDC 0.19 via x402). Returns enriched signal: composite score, sector percentile, plain-English thesis, comparables, multi-period history.'
    httpAnalog:
    - method: POST
      path: /api/agent/deep-signal
      auth: creditPackKey
      paid: true
      unitPrice: EUR 0.19
    - method: POST
      path: /api/agent/deep-signal/x402
      auth: x402
      paid: true
      unitPrice: USDC 0.19
    inputSchema:
      type: object
      properties:
        name:
          type: string
          description: Startup display name or GitHub org slug.
      required:
      - name
      additionalProperties: false
    annotations:
      readOnlyHint: false
      idempotentHint: true
      openWorldHint: false
    paid: true
  - name: share_result
    description: Compose a sharable post for X / Bluesky / Mastodon / LinkedIn / Telegram from a signal takeaway.
    httpAnalog: null
    requiresUserApproval: true
    inputSchema:
      type: object
      properties:
        text:
          type: string
          minLength: 10
          maxLength: 200
        network:
          type: string
          enum:
          - all
          - twitter
          - bluesky
          - mastodon
          - linkedin
          - telegram
          default: all
        includeAttribution:
          type: boolean
          default: true
      required:
      - text
      additionalProperties: false
    annotations:
      readOnlyHint: true
      idempotentHint: true
      openWorldHint: false
  resources:
  - uri: signal://trending
    name: Trending Startups (current week)
    description: Top 20 startups across all sectors for the current weekly period.
    mimeType: application/json
    httpAnalog: GET /api/signals.json
  - uri: signal://summary
    name: Dataset Summary
    description: Period, sector and startup counts, last refresh, format URLs.
    mimeType: application/json
    httpAnalog: GET /api/v1/signals.json (meta sub-object)
  - uri: signal://methodology
    name: Signal Methodology
    description: Full methodology document.
    mimeType: text/markdown
    httpAnalog: GET /api/v1/methodology.json
  resourceTemplates:
  - uriTemplate: signal://startup/{name}
    name: Startup Signal Profile
    description: Full profile for a single tracked startup.
    mimeType: application/json
    httpAnalog: GET /api/signal?company={name}
  - uriTemplate: signal://sector/{slug}
    name: Sector Signal Snapshot
    description: All tracked startups within a sector.
    mimeType: application/json
    httpAnalog: GET /api/signals.json (sectors[slug])
  prompts:
  - name: weekly_digest
    description: Monday-morning Signal Digest from the current top-20 trending startups.
    arguments: []
  - name: sector_deep_dive
    description: Sector intelligence brief, top movers, dark horses, thesis follow-ups.
    arguments:
    - name: sector
      description: Sector slug.
      required: true
  - name: find_dark_horse
    description: Surface one under-the-radar startup with sustained acceleration.
    arguments:
    - name: sector
      description: Optional sector slug.
      required: false
  - name: compare_startups
    description: Head-to-head investor comparison of two named startups.
    arguments:
    - name: name_a
      description: First startup.
      required: true
    - name: name_b
      description: Second startup.
      required: true
  - name: acceleration_memo
    description: One-page deal memo grounded in the live signal profile of a named startup.
    arguments:
    - name: name
      description: Startup display name or GitHub org slug.
      required: true
x-a2a:
  agentCardUrl: https://signals.gitdealflow.com/.well-known/agent-card.json
  jsonrpcEndpoint: https://signals.gitdealflow.com/api/a2a
  protocolVersion: 0.3.0
x-changelog:
- version: 1.3.0
  date: '2026-05-08'
  changes:
  - Added `info.x-rate-limit` default (60/min/IP, burst 120) so paid agents discover throttling without hitting 429.
  - Added per-operation `x-rate-limit` overrides on /api/signal (30/min/IP) and /api/receipts/{username} (10/min/IP).
  - Added `x-mcp.skillsManifest` and `x-mcp-server.skillsManifest` pointing to /.well-known/skills.json, Anthropic-style skills card enumerating the 5 MCP prompts as agent-callable skills with explicit invoke contracts.
  - Added 11 extension-stripped /api/v1/<resource> aliases (signals, faq, methodology, glossary, answers, openapi, agents, changelog, dataset, pricing, uptime) for agents that strip file extensions; canonical URLs remain at .json/.jsonl variants.
- version: 1.2.0
  date: '2026-05-07'
  changes:
  - Added x-mcp-tool extensions to 6 operations with MCP analogs (get_signals_summary, get_startup_signal, get_scout_receipts, get_methodology, get_deep_signal x2 variants).
  - Added top-level x-mcp-server with full tool/resource/prompt enumeration including HTTP analog mapping.
  - Documented 9 /api/v1/* versioned endpoints (signals, agents, answers, changelog, dataset, faq, methodology, glossary, openapi).
- version: 1.1.0
  date: '2026-04-22'
  changes:
  - Initial public spec.