GitDealFlow Scout API

openapi: 3.2.0
info:
  title: VC Deal Flow Signal Scout 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: scout
  description: Scout score receipts and prediction
paths:
  /api/receipts/{username}:
    get:
      tags:
      - scout
      operationId: getScoutReceipts
      summary: Scout Score for a GitHub user (0-100)
      description: 'Backwards-looking proof of taste: how many validated unicorns did this user star *before* the funding/$1B/acquisition event?'
      x-mcp-tool:
        name: get_scout_receipts
        description: 1:1 MCP analog. The `github_username` MCP arg maps to the `username` path parameter.
        relation: exact
        argumentMapping:
          github_username: username
        annotations:
          readOnlyHint: true
          idempotentHint: true
          openWorldHint: false
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 39
      x-rate-limit:
        requestsPerMinute: 10
        scope: ip
        burst: 20
        onExceeded:
          status: 429
          header: Retry-After
        notes: Tighter than the default because the scoring step calls the GitHub API and is bursty by nature.
      responses:
        '200':
          description: Scout score with personality + breakdown
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid GitHub username.
        '429':
          description: Rate limited (10/min/IP). Retry after the `Retry-After` header.
  /api/scout/predict:
    get:
      tags:
      - scout
      operationId: getScoutPrediction
      summary: Forward-looking scout prediction (experimental)
      description: Predicts which currently-tracked startups a given GitHub user is most likely to bet on next, using their starring history.
      parameters:
      - name: username
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Ranked predictions
          content:
            application/json:
              schema:
                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.