GitDealFlow Answer API

openapi: 3.2.0
info:
  title: VC Deal Flow Signal Answer 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: Answer
  description: Citation-ready Q&A retrieval
paths:
  /api/answer:
    get:
      tags:
      - Answer
      operationId: getAnswer
      summary: Single best answer to a question (citation-ready)
      description: Single-shot retrieval over the agent-query corpus + standalone FAQs. Returns the best match with confidence, supporting facts, and a canonical URL for verification. Designed for ChatGPT custom GPTs, Claude tool use, Perplexity actions.
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          maxLength: 280
      responses:
        '200':
          description: Top answer hit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnswerHit'
  /api/ask:
    get:
      tags:
      - Answer
      operationId: askQuestion
      summary: Top-N ranked candidates for a question
      description: Sibling of /api/answer. Returns ranked candidates instead of a single best match, for autocomplete UX or comparison.
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          maxLength: 280
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 20
          default: 5
      responses:
        '200':
          description: Ranked candidates
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
                  hits:
                    type: array
                    items:
                      $ref: '#/components/schemas/AnswerHit'
  /api/diligence.json:
    get:
      tags:
      - Answer
      operationId: getDiligenceDossier
      summary: Public-source diligence dossier for a company/entity
      description: 'One cited dossier per entity: who acquired it (M&A history), which funds publicly backed it, and its published engineering-acceleration signal. Sources are press-release / SEC-filing / both-sides-disclosed only; returns found:false (404) with honest notes when the entity is outside the tracked corpus, never guesses. Same payload as the get_diligence_dossier MCP tool. Human mirror at /diligence.'
      parameters:
      - name: company
        in: query
        required: false
        schema:
          type: string
          maxLength: 100
        description: 'Company or entity name (target, acquirer, or tracked startup). Aliases: entity, q. Omit for a usage envelope listing the answerable universe.'
      responses:
        '200':
          description: Dossier with at least one grounded fact (or usage envelope when no company param)
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@type':
                    type: string
                    example: Dataset
                  dossier:
                    type: object
                    properties:
                      entity:
                        type: string
                      found:
                        type: boolean
                      acquiredBy:
                        type: array
                        items:
                          type: object
                      acquisitionsMade:
                        type: array
                        items:
                          type: object
                      backedBy:
                        type: array
                        items:
                          type: object
                      signal:
                        type: object
                        nullable: true
                      notes:
                        type: array
                        items:
                          type: string
                  citation:
                    type: array
                    items:
                      type: object
        '404':
          description: found:false, entity outside the tracked corpus (an expected outcome, not an error)
      x-mcp-tool: get_diligence_dossier
  /api/answers.json:
    get:
      tags:
      - Answer
      operationId: getAnswersCorpus
      summary: Full Q&A corpus (agent-queries + FAQs)
      description: Bulk dump of every agent query and standalone FAQ for offline embedding / fine-tuning.
      responses:
        '200':
          description: Q&A corpus
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /api/v1/answers.json:
    get:
      tags:
      - Answer
      operationId: getAnswersV1
      summary: Versioned alias of /api/answers.json (full Q&A corpus)
      responses:
        '200':
          description: Q&A corpus
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /api/v1/faq.json:
    get:
      tags:
      - Answer
      operationId: getFaqV1
      summary: Standalone FAQ corpus (101 entries)
      description: Curated FAQ corpus separate from the agent-query firehose. Stable answer slugs, safe to cite.
      responses:
        '200':
          description: FAQ entries
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  schemas:
    AnswerHit:
      type: object
      properties:
        question:
          type: string
        answer:
          type: string
        url:
          type: string
          format: uri
        source:
          type: string
          enum:
          - agent-query
          - faq
        confidence:
          type: number
          minimum: 0
          maximum: 1
        facts:
          type: array
          items:
            type: object
            properties:
              claim:
                type: string
              sourceUrl:
                type: string
                format: uri
        related:
          type: array
          items:
            type: object
            properties:
              question:
                type: string
              url:
                type: string
                format: uri
  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)