API Evangelist agent enhancements for Bigtincan Hub Public Story API

overlay: 1.0.0
info:
  title: API Evangelist agent enhancements for Bigtincan Hub Public Story API
  version: 1.0.0
extends: openapi/bigtincan-story-api-openapi.yml
x-provenance:
  generated: '2026-10-21'
  method: generated
  source: openapi/bigtincan-story-api-openapi.yml
  description: 'Adds agent-facing hints only: an x-agent-consequence per operation (read/write/destructive/external-effect,
    derived from HTTP method and path) and the candidate MCP tool names from mcp/bigtincan-mcp.yml. Bigtincan
    ships no MCP server; the tool names are candidates. The OpenAPI file is not mutated.'
actions:
- target: $.info
  description: Record API Evangelist provenance; the source contract is the Swagger 2.0 document Bigtincan
    serves at https://pubapi.bigtincan.com/api/sandbox/swagger/public-api.
  update:
    x-apievangelist:
      provider: bigtincan
      upstream: https://pubapi.bigtincan.com/api/sandbox/swagger/public-api
      docs: https://pubapi.bigtincan.com/doc/interactive/
      mcp_manifest: mcp/bigtincan-mcp.yml
- target: $.paths['/v1/story/add/tag/{story_perm_id}'].post
  description: Agent hints for post-v1-story-add-tag-by-story-perm-id (consequence derived from HTTP method/path).
  update:
    x-agent-consequence: write
    x-mcp-candidate-tools:
    - tag_story
- target: $.paths['/v1/story/archive/{revision_id}'].delete
  description: Agent hints for delete-v1-story-archive-by-revision-id (consequence derived from HTTP method/path).
  update:
    x-agent-consequence: destructive
    x-mcp-candidate-tools:
    - archive_story
- target: $.paths['/v1/story/comment/{revision_id}'].post
  description: Agent hints for post-v1-story-comment-by-revision-id (consequence derived from HTTP method/path).
  update:
    x-agent-consequence: write
    x-mcp-candidate-tools:
    - comment_on_story
- target: $.paths['/v1/story/search'].get
  description: Agent hints for get-v1-story-search (consequence derived from HTTP method/path).
  update:
    x-agent-consequence: read
    x-mcp-candidate-tools:
    - search_stories
- target: $.paths['/v1/story/share/{revision_id}'].post
  description: Agent hints for post-v1-story-share-by-revision-id (consequence derived from HTTP method/path).
  update:
    x-agent-consequence: external-effect
    x-mcp-candidate-tools:
    - share_story
- target: $.paths['/v1/story/upload/file'].post
  description: Agent hints for post-v1-story-upload-file (consequence derived from HTTP method/path).
  update:
    x-agent-consequence: write
    x-mcp-candidate-tools:
    - upload_story_file
- target: $.paths['/v1/story/{story_perm_id}/widgets'].get
  description: Agent hints for get-v1-story-by-story-perm-id-widgets (consequence derived from HTTP method/path).
  update:
    x-agent-consequence: read
- target: $.paths['/v1.1/story/get/{story_perm_id}'].get
  description: Agent hints for get-v1-1-story-get-by-story-perm-id (consequence derived from HTTP method/path).
  update:
    x-agent-consequence: read
    x-mcp-candidate-tools:
    - get_story
- target: $.paths['/v1.2/story/all'].get
  description: Agent hints for get-v1-2-story-all (consequence derived from HTTP method/path).
  update:
    x-agent-consequence: read
    x-mcp-candidate-tools:
    - list_stories
- target: $.paths['/v1.2/story/add'].post
  description: Agent hints for post-v1-2-story-add (consequence derived from HTTP method/path).
  update:
    x-agent-consequence: write
    x-mcp-candidate-tools:
    - publish_story
- target: $.paths['/v1.2/story/edit/{revision_id}'].put
  description: Agent hints for put-v1-2-story-edit-by-revision-id (consequence derived from HTTP method/path).
  update:
    x-agent-consequence: write
    x-mcp-candidate-tools:
    - update_story