API Evangelist Guidance API

openapi: 3.2.0
info:
  title: Evangelist Network Guidance 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: Guidance
  description: Editorial guidance across the history, technology, business, politics, governance, and evangelism of APIs.
paths:
  /guidance/sections/history:
    get:
      operationId: listGuidanceHistory
      tags:
      - Guidance
      summary: History
      description: Guidance from the history of APIs — the providers, tooling, and moments that shaped the space.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: Paged guidance tagged History.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEnvelope'
              example:
                meta:
                  total: 27
                  page: 1
                  limit: 2
                  pages: 14
                  query:
                    section: history
                data:
                - slug: 3scale
                  title: 3Scale
                  summary: The freemium-first API management platform that proved the space could be self-service and sustainable.
                  url: https://guidance.apievangelist.com/store/3scale/
                  tags:
                  - History
                  - API Management
                  has_content: true
                  type: guidance
                - slug: amazon
                  title: Amazon
                  summary: The e-commerce and cloud company that bet its entire platform on APIs
                  url: https://guidance.apievangelist.com/store/amazon/
                  tags:
                  - History
                  has_content: true
                  type: guidance
          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'
  /guidance/sections/technology:
    get:
      operationId: listGuidanceTechnology
      tags:
      - Guidance
      summary: Technology
      description: Guidance on the technology of APIs — protocols, patterns, and the technical landscape.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: Paged guidance tagged Technology.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEnvelope'
              example:
                meta:
                  total: 47
                  page: 1
                  limit: 2
                  pages: 24
                  query:
                    section: technology
                data:
                - slug: agent-skills
                  title: Agent Skills
                  summary: Packaged capability units that AI agents load to execute API operations
                  url: https://guidance.apievangelist.com/store/agent-skills/
                  tags:
                  - Technology
                  has_content: true
                  type: guidance
                - slug: apis-json
                  title: APIs.json
                  summary: The machine-readable discovery format I created for indexing APIs and their operations
                  url: https://guidance.apievangelist.com/store/apis-json/
                  tags:
                  - Technology
                  has_content: true
                  type: guidance
          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'
  /guidance/sections/business:
    get:
      operationId: listGuidanceBusiness
      tags:
      - Guidance
      summary: Business
      description: Guidance on the business of APIs — monetization, plans, partners, and go-to-market.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: Paged guidance tagged Business.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEnvelope'
              example:
                meta:
                  total: 24
                  page: 1
                  limit: 2
                  pages: 12
                  query:
                    section: business
                data:
                - slug: aggregators
                  title: Aggregators
                  summary: Services that unify multiple provider APIs behind a single interface
                  url: https://guidance.apievangelist.com/store/aggregators/
                  tags:
                  - Business
                  has_content: true
                  type: guidance
                - slug: communities
                  title: Communities
                  summary: Developer communities built around an API platform or ecosystem
                  url: https://guidance.apievangelist.com/store/communities/
                  tags:
                  - Business
                  has_content: true
                  type: guidance
          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'
  /guidance/sections/politics:
    get:
      operationId: listGuidancePolitics
      tags:
      - Guidance
      summary: Politics
      description: Guidance on the politics of APIs — regulation, privacy, terms of service, and power.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: Paged guidance tagged Politics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEnvelope'
              example:
                meta:
                  total: 29
                  page: 1
                  limit: 2
                  pages: 15
                  query:
                    section: politics
                data:
                - slug: access
                  title: Access
                  summary: Who gets to call an API and under what terms
                  url: https://guidance.apievangelist.com/store/access/
                  tags:
                  - Politics
                  has_content: true
                  type: guidance
                - slug: accountability
                  title: Accountability
                  summary: Mechanisms for holding API providers responsible for their platform decisions
                  url: https://guidance.apievangelist.com/store/accountability/
                  tags:
                  - Politics
                  has_content: true
                  type: guidance
          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'
  /guidance/sections/governance:
    get:
      operationId: listGuidanceGovernance
      tags:
      - Guidance
      summary: Governance
      description: Guidance on API governance — aligning policies, rules, and lifecycle across operations.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: Paged guidance tagged Governance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEnvelope'
              example:
                meta:
                  total: 30
                  page: 1
                  limit: 2
                  pages: 15
                  query:
                    section: governance
                data:
                - slug: async
                  title: Async
                  summary: Governing asynchronous and event-driven API patterns alongside REST
                  url: https://guidance.apievangelist.com/store/async/
                  tags:
                  - Governance
                  has_content: true
                  type: guidance
                - slug: awareness
                  title: Awareness
                  summary: The understanding of your infrastructure, applications, and operations that working with APIs forces into the open
                  url: https://guidance.apievangelist.com/store/awareness/
                  tags:
                  - Governance
                  has_content: true
                  type: guidance
          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'
  /guidance/sections/evangelism:
    get:
      operationId: listGuidanceEvangelism
      tags:
      - Guidance
      summary: Evangelism
      description: Guidance on API evangelism — carrying the API message and earning adoption.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: Paged guidance tagged Evangelism.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEnvelope'
              example:
                meta:
                  total: 23
                  page: 1
                  limit: 2
                  pages: 12
                  query:
                    section: evangelism
                data:
                - slug: advocacy
                  title: Advocacy
                  summary: Public or internal championing of APIs and the developers who build on them
                  url: https://guidance.apievangelist.com/store/advocacy/
                  tags:
                  - Evangelism
                  has_content: true
                  type: guidance
                - slug: blogs
                  title: Blogs
                  summary: Owned editorial channels for publishing API stories tutorials and opinions
                  url: https://guidance.apievangelist.com/store/blogs/
                  tags:
                  - Evangelism
                  has_content: true
                  type: guidance
          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'
  /guidance:
    get:
      operationId: listGuidance
      tags:
      - Guidance
      summary: Guidance
      description: Search or browse the full guidance collection (177) — editorial guidance for API producers and consumers.
      parameters:
      - $ref: '#/components/parameters/Q'
      - $ref: '#/components/parameters/Tags'
      - $ref: '#/components/parameters/Match'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Paged guidance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEnvelope'
              example:
                meta:
                  total: 180
                  page: 1
                  limit: 2
                  pages: 90
                  query:
                    tags: null
                data:
                - slug: 3scale
                  title: 3Scale
                  summary: The freemium-first API management platform that proved the space could be self-service and sustainable.
                  url: https://guidance.apievangelist.com/store/3scale/
                  tags:
                  - History
                  - API Management
                  has_content: true
                  type: guidance
                - slug: access
                  title: Access
                  summary: Who gets to call an API and under what terms
                  url: https://guidance.apievangelist.com/store/access/
                  tags:
                  - Politics
                  has_content: true
                  type: guidance
          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'
  /guidance/{slug}:
    get:
      operationId: getGuidanceItem
      tags:
      - Guidance
      summary: Guidance Entry
      description: One entry from the guidance collection; `include=content` adds the full body.
      parameters:
      - $ref: '#/components/parameters/Slug'
      - $ref: '#/components/parameters/Include'
      responses:
        '200':
          description: The entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Doc'
              example:
                slug: 3scale
                title: 3Scale
                summary: The freemium-first API management platform that proved the space could be self-service and sustainable.
                url: https://guidance.apievangelist.com/store/3scale/
                tags:
                - History
                - API Management
                has_content: true
                type: guidance
          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'
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'
  schemas:
    PagedEnvelope:
      type: object
      properties:
        meta:
          type: object
          properties:
            total:
              type: integer
            page:
              type: integer
            limit:
              type: integer
            pages:
              type: integer
            query:
              type: object
              additionalProperties: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/Doc'
    Doc:
      type: object
      description: One network resource. Extra type-specific fields (guest, outline, party, …) appear per type.
      properties:
        type:
          type: string
        slug:
          type: string
        title:
          type: string
        summary:
          type: string
        url:
          type: string
          format: uri
        tags:
          type: array
          items:
            type: string
        date:
          type: string
        content:
          type: string
          description: Full markdown body when include=content.
      additionalProperties: true
    Error:
      type: object
      properties:
        error:
          type: string
        detail:
          type: string
  parameters:
    Fields:
      name: fields
      in: query
      description: Comma-separated sparse field projection.
      schema:
        type: string
        example: slug,title,url
    Q:
      name: q
      in: query
      description: Free-text query over title, summary, tags, and body.
      schema:
        type: string
    Slug:
      name: slug
      in: path
      required: true
      schema:
        type: string
    Include:
      name: include
      in: query
      description: Set to `content` to inline the full markdown body (up to 200 KB).
      schema:
        type: string
        enum:
        - content
    Tags:
      name: tags
      in: query
      description: Comma-separated tag slugs.
      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
    Match:
      name: match
      in: query
      description: Tag match mode.
      schema:
        type: string
        enum:
        - any
        - all
        default: any
  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