API Evangelist Operations API

openapi: 3.2.0
info:
  title: Evangelist Network Operations 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: Operations
  description: Strategies, experiences, and the stops along the API lifecycle.
paths:
  /strategies:
    get:
      operationId: listStrategies
      tags:
      - Operations
      summary: Strategies
      description: Search or browse the strategies collection (75) — API strategy patterns.
      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 strategies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEnvelope'
              example:
                meta:
                  total: 75
                  page: 1
                  limit: 2
                  pages: 38
                  query:
                    tags: null
                data:
                - slug: api-authentication-is-standardized
                  title: API Authentication Is Standardized
                  summary: All APIs must use standardized authentication mechanisms including OAuth, JWT, and API keys with properly defined scopes, ensuring that security is consistently implemented and that consumers have a predictable experience when authenticating across all APIs.
                  url: https://strategies.apievangelist.com/store/api-authentication-is-standardized/
                  tags: []
                  has_content: false
                  type: strategies
                - slug: api-authorization-is-properly-defined-and-enforced
                  title: API Authorization Is Properly Defined and Enforced
                  summary: All APIs must have clearly defined authorization models that control what authenticated consumers can access and perform, using role-based or attribute-based access control to ensure that permissions are granular, auditable, and consistently enforced across all API operations.
                  url: https://strategies.apievangelist.com/store/api-authorization-is-properly-defined-and-enforced/
                  tags: []
                  has_content: false
                  type: strategies
          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'
  /strategies/{slug}:
    get:
      operationId: getStrategiesItem
      tags:
      - Operations
      summary: Strategy
      description: One entry from the strategies 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: api-authentication-is-standardized
                title: API Authentication Is Standardized
                summary: All APIs must use standardized authentication mechanisms including OAuth, JWT, and API keys with properly defined scopes, ensuring that security is consistently implemented and that consumers have a predictable experience when authenticating across all APIs.
                url: https://strategies.apievangelist.com/store/api-authentication-is-standardized/
                tags: []
                has_content: false
                type: strategies
          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'
  /experiences:
    get:
      operationId: listExperiences
      tags:
      - Operations
      summary: Experiences
      description: Search or browse the experiences collection (46) — API producer and consumer experience patterns.
      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 experiences.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEnvelope'
              example:
                meta:
                  total: 46
                  page: 1
                  limit: 2
                  pages: 23
                  query:
                    tags: null
                data:
                - slug: access
                  title: Access
                  summary: 'Gaining the necessary access to effectively use an API is often more challenging than it appears. Intentional and unintentional barriers can create friction in discovering and onboarding with an API. Issues such as incomplete documentation and complex authentication processes frequently hinder adoption. These challenges often reflect the business dynamics and internal politics of making APIs available to teams, partners, and third-party developers.

                    While API access may seem straightforward to the developers who created it—or to those accustomed to high-friction onboarding—it often overlooks critical steps that could simplify the process for others. Improving the API access experience can be as simple as providing clearer instructions, maintaining regular communication, and adopting the perspective of an API consumer. By walking through your own APIs or evaluating competitors’ offerings, you can identify opportunities to streamline access and improve usability.'
                  url: https://experiences.apievangelist.com/store/access/
                  tags:
                  - Availability
                  - Discovery
                  has_content: false
                  type: experiences
                - slug: advocacy
                  title: Advocacy
                  summary: 'Advocacy is the experience of an API having someone in its corner, speaking up for its consumers and carrying their needs back into the operation. Developer relations, evangelism, and outreach are how a provider shows it cares about the people building on its API rather than just shipping endpoints and walking away. Good advocacy turns an API from a product into a relationship.

                    I have spent my whole career on the advocacy side of APIs, so I know how much it matters when someone inside an operation is genuinely fighting for consumers. Advocacy means writing the content, running the outreach, and closing the loop between what developers struggle with and what the team builds next. The APIs that invest in advocacy are the ones that build durable, loyal communities.'
                  url: https://experiences.apievangelist.com/store/advocacy/
                  tags:
                  - Evangelism
                  - Communication
                  - Community
                  has_content: false
                  type: experiences
          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'
  /experiences/{slug}:
    get:
      operationId: getExperiencesItem
      tags:
      - Operations
      summary: Experience
      description: One entry from the experiences 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: access
                title: Access
                summary: 'Gaining the necessary access to effectively use an API is often more challenging than it appears. Intentional and unintentional barriers can create friction in discovering and onboarding with an API. Issues such as incomplete documentation and complex authentication processes frequently hinder adoption. These challenges often reflect the business dynamics and internal politics of making APIs available to teams, partners, and third-party developers.

                  While API access may seem straightforward to the developers who created it—or to those accustomed to high-friction onboarding—it often overlooks critical steps that could simplify the process for others. Improving the API access experience can be as simple as providing clearer instructions, maintaining regular communication, and adopting the perspective of an API consumer. By walking through your own APIs or evaluating competitors’ offerings, you can identify opportunities to streamline access and improve usability.'
                url: https://experiences.apievangelist.com/store/access/
                tags:
                - Availability
                - Discovery
                has_content: false
                type: experiences
          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'
  /lifecycle:
    get:
      operationId: listLifecycle
      tags:
      - Operations
      summary: Lifecycle
      description: Search or browse the lifecycle collection (29) — stops along the API lifecycle.
      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 lifecycle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEnvelope'
              example:
                meta:
                  total: 29
                  page: 1
                  limit: 2
                  pages: 15
                  query:
                    tags: null
                data:
                - slug: analytics
                  title: Analytics
                  summary: Analytics turns raw API activity into understanding. Who is using what, how often, and to what end tells me where the value is and where the friction lives. I use analytics to make product decisions instead of guessing at them.
                  url: https://lifecycle.apievangelist.com/store/analytics/
                  tags:
                  - Analytics
                  - Observability
                  - Business
                  has_content: false
                  type: lifecycle
                - slug: authentication
                  title: Authentication
                  summary: Authentication is where access begins. Keys, OAuth, JWT, and mTLS each make sense in different contexts, and I pick the approach that fits the consumer and the risk. Getting authentication right is what makes an API both usable and defensible at the same time.
                  url: https://lifecycle.apievangelist.com/store/authentication/
                  tags:
                  - Security
                  - Authentication
                  - Access
                  has_content: false
                  type: lifecycle
          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'
  /lifecycle/{slug}:
    get:
      operationId: getLifecycleItem
      tags:
      - Operations
      summary: Lifecycle Stage
      description: One stop along the API lifecycle; `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: analytics
                title: Analytics
                summary: Analytics turns raw API activity into understanding. Who is using what, how often, and to what end tells me where the value is and where the friction lives. I use analytics to make product decisions instead of guessing at them.
                url: https://lifecycle.apievangelist.com/store/analytics/
                tags:
                - Analytics
                - Observability
                - Business
                has_content: false
                type: lifecycle
          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