openapi: 3.2.0
info:
  title: Evangelist Network Insights API
  version: 1.2.0
  summary: Sixteen years of API research as one API.
  description: 'The API Evangelist network — 5,000+ stories, 77 topic areas, 2,400+ governance building

    blocks (guidance, rules, policies, standards, strategies, schema, properties, experiences,

    lifecycle), conversations, videos, white papers, tools, timelines, services, and the API

    vocabulary — served as a single, searchable REST API.


    **Tiers.** The API works without a key on the free tier (5 req/s, 1,000 req/day). Requests

    from apievangelist.com network sites get the internal tier automatically. Higher-limit keys

    are available by request — email info@apievangelist.com.


    **Providers.** The API provider catalog (4,500+ companies) intentionally lives on

    [APIs.io](https://apis.io/developer/) — this API covers API Evangelist''s own research

    network and does not duplicate it.


    **MCP.** Every resource here is also available as MCP tools at

    `https://mcp.apievangelist.com/mcp` (Streamable HTTP), including concierge tools

    (`get_overview`, `guide_topic`) that bundle curated guidance for a topic.

    '
  contact:
    name: API Evangelist
    email: info@apievangelist.com
    url: https://apievangelist.com
  license:
    name: CC BY-SA 4.0
    url: https://creativecommons.org/licenses/by-sa/4.0/
servers:
- url: https://api.apievangelist.com/v1
security:
- {}
- ApiKeyAuth: []
tags:
- name: Insights
  description: Demand-side intelligence — what ~5,800 companies (Fortune 1000 + API providers) build, buy, and hire for around APIs, data, and AI. Discovery is free; per-company depth + gaps are Pro. (The supply↔demand provider match lives on apis.io.)
paths:
  /insights:
    get:
      operationId: getInsightsSummary
      x-mcp-tool: find_company_insights
      tags:
      - Insights
      summary: Insights overview.
      description: Company/dimension/adoption counts and the top investment dimensions. Free.
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                meta:
                  generated_note: stamp date at deploy — Date.now() unavailable in this harness
                  quarters:
                  - q1-2026
                  - q2-2026
                  primary_quarter: q2-2026
                  companies: 5804
                  companies_f1000: 947
                  companies_from_blogs: 4857
                  companies_with_q1: 295
                  q1_note: Q1 partial (~316 cos) + method-drifted vs Q2; served flagged, NOT diffed. See time-series.md.
                  sources: jobs + press (F1000). Provider/blog corpus extraction pending — see ingestion-evaluation.md.
                  matcher: hardened (word-boundary + stoplist, re-extracted from job corpus)
                  adoption_basis: recomputed company counts from cleaned stacks
                  corpus_audit:
                    date: '2026-08-06'
                    withheld_companies: 113
                    reason: Attribution audit of all 879 job corpora found these accounts holding another company's job board — the pull matched on company NAME and followed a vendor or partner's board. Per-company demand figures for them are withheld.
                    caveat: Aggregate figures below — dimensions, adoption and provider_demand — were computed before this audit and still include the withheld corpora. They are being rebuilt.
                    reference: https://github.com/api-evangelist/roadmap/issues/17
                top_dimensions:
                - dimension: data
                  total_signal: 40111
                  companies_with_signal: 817
                - dimension: operations
                  total_signal: 27084
                  companies_with_signal: 840
                - dimension: cloud
                  total_signal: 24024
                  companies_with_signal: 807
                - dimension: roiBusinessMetrics
                  total_signal: 22814
                  companies_with_signal: 780
                - dimension: governance
                  total_signal: 22153
                  companies_with_signal: 827
                - dimension: automation
                  total_signal: 21341
                  companies_with_signal: 790
                - dimension: code
                  total_signal: 19564
                  companies_with_signal: 832
                - dimension: security
                  total_signal: 18463
                  companies_with_signal: 930
                - dimension: ai
                  total_signal: 15834
                  companies_with_signal: 775
                - dimension: services
                  total_signal: 13682
                  companies_with_signal: 833
                counts:
                  companies: 5804
                  services: 566
                  tools: 286
                  industries: 50
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Window:
              $ref: '#/components/headers/XRateLimitWindow'
            X-RateLimit-Tier:
              $ref: '#/components/headers/XRateLimitTier'
  /insights/dimensions:
    get:
      operationId: listInsightDimensions
      x-mcp-tool: insights_dimensions
      tags:
      - Insights
      summary: Rank the 40 investment dimensions by company signal. Free.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                meta:
                  total: 42
                  page: 1
                  limit: 2
                  pages: 21
                  query:
                    quarter: q2-2026
                data:
                - dimension: data
                  total_signal: 40111
                  companies_with_signal: 817
                - dimension: operations
                  total_signal: 27084
                  companies_with_signal: 840
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Window:
              $ref: '#/components/headers/XRateLimitWindow'
            X-RateLimit-Tier:
              $ref: '#/components/headers/XRateLimitTier'
      description: Rank the 40 investment dimensions by how much company signal sits behind each one — the demand-side view of where organisations are actually putting effort. Free tier.
  /insights/adoption:
    get:
      operationId: listInsightAdoption
      x-mcp-tool: insights_adoption
      tags:
      - Insights
      summary: Services / tools / standards ranked by adoption. Free.
      parameters:
      - name: type
        in: query
        schema:
          type: string
          enum:
          - service
          - tool
          - standard
          default: service
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                meta:
                  total: 566
                  page: 1
                  limit: 2
                  pages: 283
                  query:
                    type: services
                data:
                - name: Microsoft Office
                  slug: microsoft-office
                  companyCount: 731
                  radarRing: Optimizing
                - name: Microsoft Teams
                  slug: microsoft-teams
                  companyCount: 715
                  radarRing: Optimizing
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Window:
              $ref: '#/components/headers/XRateLimitWindow'
            X-RateLimit-Tier:
              $ref: '#/components/headers/XRateLimitTier'
      description: Services, tools and standards ranked by adoption across the profiled company set. Each response names the corpus and the matcher it was measured with. Free tier.
  /insights/industries:
    get:
      operationId: listInsightIndustries
      tags:
      - Insights
      summary: Industry rollup. Free.
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                meta:
                  total: 50
                  page: 1
                  limit: 2
                  pages: 25
                  query: {}
                data:
                - name: Industrial
                  company_count: 138
                - name: Technology
                  company_count: 135
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Window:
              $ref: '#/components/headers/XRateLimitWindow'
            X-RateLimit-Tier:
              $ref: '#/components/headers/XRateLimitTier'
      description: The same adoption picture rolled up by industry, so a dimension can be read against the sector it shows up in. Free tier.
  /insights/companies:
    get:
      operationId: listInsightCompanies
      x-mcp-tool: find_company_insights
      tags:
      - Insights
      summary: Browse profiled companies by name, ranked by readiness. Free.
      parameters:
      - $ref: '#/components/parameters/Q'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                meta:
                  total: 5804
                  page: 1
                  limit: 2
                  pages: 2902
                  query: {}
                data:
                - slug: goldman-sachs
                  name: Goldman Sachs
                  industry: Financial Technology
                  sub_sector: Payment Processing
                  readiness_total: 1756
                - slug: leidos
                  name: Leidos
                  industry: Enterprise Software
                  sub_sector: IT Service Management
                  readiness_total: 1749
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Window:
              $ref: '#/components/headers/XRateLimitWindow'
            X-RateLimit-Tier:
              $ref: '#/components/headers/XRateLimitTier'
      description: Browse the profiled companies by name, ranked by readiness total. The index behind the per-company profiles. Free tier.
  /insights/company/{slug}:
    get:
      operationId: getCompanyInsight
      x-mcp-tool: get_company_insight
      tags:
      - Insights
      summary: One company's demand-side profile — thin preview (free) or full 40-dimension profile (Pro).
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                slug: goldman-sachs
                name: Goldman Sachs
                industry: Financial Technology
                sub_sector: Payment Processing
                source: jobs
                confidence: high
                readiness_total: 1756
                top_dimensions:
                - key: data
                  score: 193
                - key: cloud
                  score: 119
                - key: operations
                  score: 112
                sample_gap:
                  dimension: domainSpecialization
                  score: 2
                quarters:
                - q2-2026
                - q1-2026
                upgrade: Preview is deliberately thin. Pro unlocks the full 40-dimension profile, adoption stack, per-quarter history, gaps, and provider matches. https://apis.io/developer/plans/
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Window:
              $ref: '#/components/headers/XRateLimitWindow'
            X-RateLimit-Tier:
              $ref: '#/components/headers/XRateLimitTier'
        '404':
          $ref: '#/components/responses/NotFound'
      description: One company's demand-side profile. The free tier returns a thin preview; Pro returns the full 40-dimension profile with the evidence behind each dimension.
  /insights/company/{slug}/gaps:
    get:
      operationId: getCompanyGaps
      x-tier: pro
      x-mcp-tool: company_gaps
      security:
      - ApiKeyAuth: []
      tags:
      - Insights
      summary: PRO — a company's weakest investment dimensions.
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Window:
              $ref: '#/components/headers/XRateLimitWindow'
            X-RateLimit-Tier:
              $ref: '#/components/headers/XRateLimitTier'
        '403':
          description: Requires the Pro tier.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
      description: A company's weakest investment dimensions — where the signal is thinnest relative to its peers. Pro only.
components:
  headers:
    XRateLimitTier:
      description: The tier this request was served on — `free`, `pro`, `business`, `internal` or `owner`. Keyless requests are `free`; requests from an apievangelist.com origin are `internal`.
      schema:
        type: string
        examples:
        - free
    XRateLimitLimit:
      description: The daily request quota for the tier that served this response.
      schema:
        type: integer
        examples:
        - 1000
    XRateLimitWindow:
      description: The quota window in seconds. Always 86400 (one day).
      schema:
        type: integer
        examples:
        - 86400
    RateLimitPolicy:
      description: 'The rate-limit policy in force for the tier that served this response, in RFC 9331 quota-policy syntax: `"quota";q=1000;w=86400, "burst";q=5;w=1` — a daily quota and a per-second burst. This is the POLICY, not a live counter: `RateLimit-Remaining` and `RateLimit-Reset` are deliberately not sent, because the quota is enforced by the gateway and there is no per-key usage accounting to read. Pace against the policy, and treat a 429 as authoritative.'
      schema:
        type: string
        examples:
        - '"quota";q=1000;w=86400, "burst";q=5;w=1'
  parameters:
    Q:
      name: q
      in: query
      description: Free-text query over title, summary, tags, and body.
      schema:
        type: string
    Page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        detail:
          type: string
  responses:
    NotFound:
      description: No such resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Optional — raises rate limits above the keyless free tier.
x-apis-io:
  tiers:
    free:
      label: Free
      description: Browse, search, and read summaries across the whole network — stories, areas, guidance, building blocks, papers, tags, related. Keyless.
    pro:
      label: Pro
      description: The research depth — full content (include=content), curated topic guides (/guide), and catalog intelligence (/stats). Requires X-API-Key.
      plans: https://developer.apievangelist.com/plans/
  mcp:
    endpoint: https://mcp.apievangelist.com/mcp
  agentSkills:
    index: https://apievangelist.com/.well-known/agent-skills/index.json
  prompts:
  - name: where_can_ae_help
    tier: free
    description: Map a team's API need to the relevant research areas + the services Kin Lane offers.
    uses:
    - search_api_evangelist
    - find_services
  - name: catch_up
    tier: free
    description: Catch up on a topic — the most recent stories, newest first.
    uses:
    - find_posts
  - name: research_topic
    tier: pro
    description: 'PRO — Deep-research a topic: the curated guide bundle plus the full research bodies.'
    uses:
    - guide_topic
    - get_post
    - find_related
  - name: governance_starter_kit
    tier: pro
    description: 'PRO — Assemble an API governance starter kit: guidance, rules, policies, standards + services.'
    uses:
    - guide_topic
    - find_building_blocks
  - name: vendor_landscape
    tier: pro
    description: PRO — Map the vendor + tooling landscape for a capability, with research context.
    uses:
    - find_solutions
    - find_tools
    - guide_topic
  resources:
  - uri: ae://overview
    tier: free
    description: Service root — what the network offers, counts, entry points, how to engage.
    operation: getServiceInfo
  - uri: ae://services
    tier: free
    description: The services Kin Lane offers teams.
    operation: listServices
  - uri: ae://contact
    tier: free
    description: Every way to reach API Evangelist.
    operation: getContact
  - uri: ae://stats
    tier: pro
    description: PRO — per-type counts, stories-per-year, top tags by reach.
    operation: getStats
  - uri: ae://area/{slug}
    tier: free
    description: One topic area with its related-area graph.
    operation: getArea
  - uri: ae://tag/{slug}
    tier: free
    description: One tag with per-type counts and everything it labels.
    operation: getTag
  - uri: ae://post/{slug}
    tier: free
    description: One story by slug.
    operation: getPost
  - uri: ae://guide/{topic}
    tier: pro
    description: PRO — a curated cross-network guide bundle for a topic.
    operation: getGuide
  operations:
    getServiceInfo:
      tier: free
      mcpTool: get_overview
    searchNetwork:
      tier: free
      mcpTool: search_api_evangelist
      agentSkill: brief-on-topic
    listPosts:
      tier: free
      mcpTool: find_posts
      agentSkill: brief-on-topic
    getPost:
      tier: free
      mcpTool: get_post
    listAreas:
      tier: free
      mcpTool: find_areas
      agentSkill: brief-on-topic
    getArea:
      tier: free
      mcpTool: get_area
    listGuidanceHistory:
      tier: free
      mcpTool: get_guidance_section
    listGuidanceTechnology:
      tier: free
      mcpTool: get_guidance_section
    listGuidanceBusiness:
      tier: free
      mcpTool: get_guidance_section
    listGuidancePolitics:
      tier: free
      mcpTool: get_guidance_section
    listGuidanceGovernance:
      tier: free
      mcpTool: get_guidance_section
    listGuidanceEvangelism:
      tier: free
      mcpTool: get_guidance_section
    listGuidance:
      tier: free
      mcpTool: find_building_blocks
      agentSkill: governance-starter-kit
    getGuidanceItem:
      tier: free
      mcpTool: get_building_block
    listPolicies:
      tier: free
      mcpTool: find_building_blocks
      agentSkill: governance-starter-kit
    getPoliciesItem:
      tier: free
      mcpTool: get_building_block
    listRules:
      tier: free
      mcpTool: find_building_blocks
      agentSkill: governance-starter-kit
    getRulesItem:
      tier: free
      mcpTool: get_building_block
    listStandards:
      tier: free
      mcpTool: find_building_blocks
      agentSkill: governance-starter-kit
    getStandardsItem:
      tier: free
      mcpTool: get_building_block
    listSolutions:
      tier: free
      mcpTool: find_solutions
      agentSkill: map-vendor-landscape
    getSolution:
      tier: free
      mcpTool: get_solution
    listTools:
      tier: free
      mcpTool: find_tools
      agentSkill: map-vendor-landscape
    getTool:
      tier: free
      mcpTool: get_tool
    listSchema:
      tier: free
      mcpTool: find_building_blocks
    getSchemaItem:
      tier: free
      mcpTool: get_building_block
    listProperties:
      tier: free
      mcpTool: find_building_blocks
    getPropertiesItem:
      tier: free
      mcpTool: get_building_block
    listStrategies:
      tier: free
      mcpTool: find_building_blocks
    getStrategiesItem:
      tier: free
      mcpTool: get_building_block
    listExperiences:
      tier: free
      mcpTool: find_building_blocks
    getExperiencesItem:
      tier: free
      mcpTool: get_building_block
    listLifecycle:
      tier: free
      mcpTool: find_building_blocks
    getLifecycleItem:
      tier: free
      mcpTool: get_building_block
    listConversations:
      tier: free
      mcpTool: find_conversations
    getConversation:
      tier: free
      mcpTool: get_conversation
    listVideos:
      tier: free
      mcpTool: find_videos
    getVideo:
      tier: free
      mcpTool: get_video
    listPapers:
      tier: free
      mcpTool: find_papers
      agentSkill: research-with-api-evangelist
    getPaper:
      tier: free
      mcpTool: get_paper
    listNewsletters:
      tier: free
      mcpTool: search_api_evangelist
    listVocabulary:
      tier: free
      mcpTool: find_vocabulary
    listVocabularyCategory:
      tier: free
      mcpTool: find_vocabulary
    listFeeds:
      tier: free
      mcpTool: get_feeds
    getTimelineApi:
      tier: free
      mcpTool: get_timeline
    getTimelineResources:
      tier: free
      mcpTool: get_timeline
    getTimelineIndustries:
      tier: free
      mcpTool: get_timeline
    getTimelinePeople:
      tier: free
      mcpTool: get_timeline
    listServices:
      tier: free
      mcpTool: find_services
      agentSkill: find-where-ae-helps
    getService:
      tier: free
      mcpTool: get_service
      agentSkill: find-where-ae-helps
    getContact:
      tier: free
      mcpTool: get_contact
      agentSkill: find-where-ae-helps
    listTags:
      tier: free
      mcpTool: find_tags
      agentSkill: brief-on-topic
    getTag:
      tier: free
      mcpTool: get_tag
      agentSkill: brief-on-topic
    getGuide:
      tier: pro
      mcpTool: guide_topic
      agentSkill: research-with-api-evangelist
    getStats:
      tier: pro
      mcpTool: get_stats
    getPostRelated:
      tier: free
      mcpTool: find_related
      agentSkill: brief-on-topic
    getAreaRelated:
      tier: free
      mcpTool: find_related
      agentSkill: brief-on-topic
    getPaperRelated:
      tier: free
      mcpTool: find_related
      agentSkill: research-with-api-evangelist
    getGuidanceRelated:
      tier: free
      mcpTool: find_related
      agentSkill: brief-on-topic