GitDealFlow Signals API

openapi: 3.2.0
info:
  title: VC Deal Flow Signal Signals 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: Signals
  description: Startup engineering acceleration data
paths:
  /api/signals.json:
    get:
      tags:
      - Signals
      operationId: getSignals
      summary: Full snapshot of startup engineering signals (free)
      description: 'Returns the current period''s data: meta, top-20 trending, and per-sector rankings with commit velocity, contributor growth, and signal classification.'
      x-mcp-tool:
        name: get_signals_summary
        description: MCP analog projects this response to the meta + format-URL summary; full data is reachable as the `signal://summary` MCP resource and the `signal://trending` MCP resource.
        relation: superset
        annotations:
          readOnlyHint: true
          idempotentHint: true
          openWorldHint: false
      responses:
        '200':
          description: Successful response with all signal data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignalsResponse'
  /api/signals.csv:
    get:
      tags:
      - Signals
      operationId: getSignalsCSV
      summary: Same data as signals.json in CSV form
      responses:
        '200':
          description: CSV file with all startup signals
          content:
            text/csv:
              schema:
                type: string
  /api/signal:
    get:
      tags:
      - Signals
      operationId: getSingleSignal
      summary: Single startup signal by company name
      x-mcp-tool:
        name: get_startup_signal
        description: 1:1 MCP analog. The `name` MCP arg maps to the `company` query parameter. Reachable via the `signal://startup/{name}` MCP resource template.
        relation: exact
        argumentMapping:
          name: company
        annotations:
          readOnlyHint: true
          idempotentHint: true
          openWorldHint: false
      parameters:
      - name: company
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 80
        description: Display name or GitHub org slug. Case-insensitive fuzzy match.
      x-rate-limit:
        requestsPerMinute: 30
        scope: ip
        burst: 60
        onExceeded:
          status: 429
          header: Retry-After
      responses:
        '200':
          description: 'Best-match startup or { found: false }.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Startup'
        '400':
          description: Missing company parameter.
        '429':
          description: Rate limited (30/min/IP). Retry after the `Retry-After` header.
  /api/dataset.jsonl:
    get:
      tags:
      - Signals
      operationId: getDatasetJsonl
      summary: Full per-startup dataset (NDJSON)
      description: Newline-delimited JSON dump suitable for streaming into pandas, DuckDB, or a training pipeline. CC BY 4.0.
      responses:
        '200':
          description: JSONL stream
          content:
            application/x-ndjson:
              schema:
                type: string
  /api/v1/signals.json:
    get:
      tags:
      - Signals
      operationId: getSignalsV1
      summary: Versioned alias of /api/signals.json
      description: Stable v1 path for procurement automations and agents that pin to a versioned URL. Body identical to /api/signals.json. Canonical URL declared via Link rel=canonical header.
      responses:
        '200':
          description: Successful response with all signal data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignalsResponse'
  /api/v1/dataset.jsonl:
    get:
      tags:
      - Signals
      operationId: getDatasetJsonlV1
      summary: Versioned alias of /api/dataset.jsonl (NDJSON dataset)
      responses:
        '200':
          description: NDJSON stream of every tracked startup × period.
          content:
            application/x-ndjson:
              schema:
                type: string
components:
  schemas:
    Sector:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
        startupCount:
          type: integer
        startups:
          type: array
          items:
            $ref: '#/components/schemas/Startup'
    Startup:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        stage:
          type: string
          enum:
          - Pre-seed
          - Seed
          - Series A/B
          - Growth
        geography:
          type: string
        commitVelocity14d:
          type: integer
          description: Total commits over a rolling 14-day window
        commitVelocityChange:
          type: string
          description: Percentage change vs. prior 14-day window (e.g., '+120%')
        contributors:
          type: integer
        contributorGrowth:
          type: string
        newRepos:
          type: integer
        signalType:
          type: string
          enum:
          - Engineering hiring burst
          - Infrastructure buildout
          - Deploy frequency spike
          - Framework migration
        githubUrl:
          type: string
          format: uri
        websiteUrl:
          type: string
          format: uri
        linkedinUrl:
          type: string
          format: uri
    SignalsResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            name:
              type: string
            period:
              type: object
              properties:
                slug:
                  type: string
                name:
                  type: string
            totalSectors:
              type: integer
            totalStartups:
              type: integer
            lastUpdated:
              type: string
              format: date-time
            citation:
              type: string
        trending:
          type: array
          items:
            $ref: '#/components/schemas/Startup'
        sectors:
          type: array
          items:
            $ref: '#/components/schemas/Sector'
  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.
x-provenance:
  method: harvested
  publisher: GitDealFlow
  source: https://signals.gitdealflow.com/api/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)