Knostic AgentMesh API

# Knostic AgentMesh API — OpenAPI 3.1
# generated: 2026-07-19
# method: generated
# source: https://agentmesh.knostic.ai/api (provider-published API reference)
openapi: 3.1.0
info:
  title: Knostic AgentMesh API
  version: 1.0.0
  description: 'AgentMesh is Knostic''s reputation and threat-intelligence service for the AI agent supply
    chain. It continuously discovers, tracks and scans AI agent skills, MCP (Model Context Protocol) servers,
    and VS Code / IDE extensions for prompt injection and supply-chain threats, and exposes the resulting
    catalog and scan verdicts over a read API plus an on-demand scan API.


    Read endpoints (`/skills`, `/mcp`, `/extensions`) are served to anonymous callers at a reduced tier
    (responses carry an `X-Tier: anonymous` header); scan endpoints (`/scan/*`, `/scans`) require an API
    key minted from the AgentMesh console.'
  contact:
    name: Knostic
    url: https://www.knostic.ai/
    email: support@knostic.ai
  termsOfService: https://www.knostic.ai/terms-of-service
servers:
- url: https://agentmesh.knostic.ai/api
  description: Production
tags:
- name: skills
  description: AI agent skills (SKILL.md) discovered and scanned by AgentMesh
- name: mcp
  description: Model Context Protocol servers discovered and scanned by AgentMesh
- name: extensions
  description: VS Code / IDE marketplace extensions with risk assessment
- name: scans
  description: On-demand security scans and scan history (API key required)
security:
- bearerAuth: []
paths:
  /skills:
    get:
      operationId: listSkills
      summary: List skills
      description: Returns a paginated list of AI agent skills with scan status, stars, and metadata.
        Supports full-text search across name and description fields.
      tags:
      - skills
      responses:
        '200':
          description: Paginated array of skill summaries with scan metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  skills:
                    type: array
                    description: Array of skill objects
                    items:
                      $ref: '#/components/schemas/SkillSummary'
                  total:
                    type: integer
                    description: Total matching skills
                  page:
                    type: integer
                    description: Current page
                  limit:
                    type: integer
                    description: Page size
              examples:
                default:
                  summary: Provider-published example
                  value:
                    skills:
                    - id: 42
                      name: browser-use
                      gitRepo: https://github.com/anthropics/browser-use
                      skillPath: SKILL.md
                      description: Browser automation skill for web agents
                      sourceUrl: https://github.com/anthropics/awesome-mcp-servers
                      stars: 1840
                      license: MIT
                      archived: false
                      latestVersionAt: '2026-01-15T09:30:00'
                      scanStatus: pass
                      latestScanAt: '2026-01-16T02:00:00'
                      contributor: hwchase17
                      fileSha256: 31795b157afee1d4441887452f6891c2b6c20538b8ed8a9b1c2d3e4f50617283
                    total: 1
                    page: 1
                    limit: 50
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                default:
                  value:
                    detail: missing or invalid api key
      parameters:
      - name: q
        in: query
        required: false
        description: Search query — matches against skill name and description (ILIKE)
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: Sort field
        schema:
          type: string
          enum:
          - recent
          - name
          - status
          - stars
          - scanned
          default: recent
      - name: dir
        in: query
        required: false
        description: Sort direction. Defaults to DESC for recent/stars, ASC for name
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: status
        in: query
        required: false
        description: Filter by scan status
        schema:
          type: string
          enum:
          - dangerous
          - risky
          - safe
          - unscanned
      - name: source
        in: query
        required: false
        description: Filter by source URL (ILIKE match)
        schema:
          type: string
      - name: hash
        in: query
        required: false
        description: 'Filter by SHA-256 hash (64 hex characters) of the archived artifact bytes. Matches
          across versions: the artifact appears if any of its versions has this hash, even if the latest
          version was rebuilt with a different hash. The displayed row is the most recent version that
          matched. Composes with q, status, and source.'
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number (1-indexed)
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        required: false
        description: Results per page (1–200)
        schema:
          type: integer
          default: 50
  /skills/{skill_id}:
    get:
      operationId: getSkill
      summary: Get skill
      description: Returns full details for a single skill including version history, scan results for
        the selected version, and repository metadata.
      tags:
      - skills
      responses:
        '200':
          description: Full skill object with nested versions and scan results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Skill ID
                  name:
                    type: string
                    description: Skill name
                  gitRepo:
                    type: string
                    description: GitHub repository URL
                  skillPath:
                    type: string
                    description: Path to SKILL.md in the repo
                  description:
                    type:
                    - string
                    - 'null'
                    description: Skill description
                  sourceUrl:
                    type:
                    - string
                    - 'null'
                    description: URL of the aggregator/source page where this skill was discovered
                  scanStatus:
                    type: string
                    description: Aggregate scan status for the selected version
                  stars:
                    type:
                    - integer
                    - 'null'
                    description: GitHub stars
                  forks:
                    type:
                    - integer
                    - 'null'
                    description: GitHub forks
                  license:
                    type:
                    - string
                    - 'null'
                    description: SPDX license identifier
                  archived:
                    type:
                    - boolean
                    - 'null'
                    description: Whether the upstream GitHub repo is archived
                  repoCreatedAt:
                    type:
                    - string
                    - 'null'
                    description: ISO-8601 timestamp when the upstream repo was created
                  lastPushedAt:
                    type:
                    - string
                    - 'null'
                    description: ISO-8601 timestamp of the last push to the upstream repo
                  contributor:
                    type:
                    - string
                    - 'null'
                    description: GitHub login of the most recent committer, or null if unknown
                  versions:
                    type: array
                    description: All tracked versions of this skill, newest first
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Version ID — used as version_id in /skills/:id/versions/:vid
                        commitHash:
                          type: string
                          description: Git commit SHA at this version
                        commitTimestamp:
                          type:
                          - string
                          - 'null'
                          description: ISO-8601 timestamp of the commit
                        scanSummary:
                          type: string
                          description: Aggregate scan status for this version
                        fileSha256:
                          type:
                          - string
                          - 'null'
                          description: SHA-256 hash (lowercase hex) of the archived artifact at this version.
                            null until the upstream pipeline computes it.
                  scanResults:
                    type: array
                    description: Scan results for the selected version
                    items:
                      type: object
                      properties:
                        scannerName:
                          type: string
                          description: Scanner identifier (e.g. 'nova')
                        scannerVersion:
                          type: string
                          description: Version of the scanner that produced this result
                        result:
                          type: string
                          description: Scan verdict (pass, warn, fail, error)
                        details:
                          type:
                          - object
                          - 'null'
                          description: Scanner-specific output (rules matched, files scanned, etc.)
                        scannedAt:
                          type:
                          - string
                          - 'null'
                          description: ISO-8601 timestamp when the scan ran
              examples:
                default:
                  summary: Provider-published example
                  value:
                    id: 42
                    name: browser-use
                    gitRepo: https://github.com/anthropics/browser-use
                    skillPath: SKILL.md
                    description: Browser automation skill for web agents
                    sourceUrl: https://github.com/anthropics/awesome-mcp-servers
                    scanStatus: pass
                    stars: 1840
                    forks: 210
                    license: MIT
                    archived: false
                    repoCreatedAt: '2025-03-01T00:00:00'
                    lastPushedAt: '2026-01-15T09:30:00'
                    contributor: hwchase17
                    versions:
                    - id: 101
                      commitHash: a1b2c3d
                      commitTimestamp: '2026-01-15T09:30:00'
                      scanSummary: pass
                      fileSha256: 31795b157afee1d4441887452f6891c2b6c20538b8ed8a9b1c2d3e4f50617283
                    scanResults:
                    - scannerName: nova
                      scannerVersion: 1.2.0
                      result: pass
                      details:
                        rulesMatched: 0
                        rulesChecked: 47
                      scannedAt: '2026-01-16T02:00:00'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                default:
                  value:
                    detail: missing or invalid api key
        '404':
          description: Skill not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                default:
                  value:
                    detail: skill not found
      parameters:
      - name: skill_id
        in: path
        required: true
        description: Skill ID
        schema:
          type: integer
      - name: version_id
        in: query
        required: false
        description: Select a specific version for scan results. Defaults to the latest version.
        schema:
          type: integer
  /skills/{skill_id}/versions/{version_id}:
    get:
      operationId: getVersionScans
      summary: Get version scan results
      description: Returns all scan results for a specific skill version. Useful for inspecting historical
        scan data across scanner versions.
      tags:
      - skills
      responses:
        '200':
          description: Scan results for the specified version.
          content:
            application/json:
              schema:
                type: object
                properties:
                  skillId:
                    type: integer
                    description: Skill ID
                  versionId:
                    type: integer
                    description: Version ID
                  scanResults:
                    type: array
                    description: Array of scan result objects
                    items:
                      type: object
                      properties:
                        scannerName:
                          type: string
                          description: Scanner identifier (e.g. 'nova')
                        scannerVersion:
                          type: string
                          description: Version of the scanner that produced this result
                        result:
                          type: string
                          description: Scan verdict (pass, warn, fail, error)
                        details:
                          type:
                          - object
                          - 'null'
                          description: Scanner-specific output (rules matched, files scanned, etc.)
                        scannedAt:
                          type:
                          - string
                          - 'null'
                          description: ISO-8601 timestamp when the scan ran
              examples:
                default:
                  summary: Provider-published example
                  value:
                    skillId: 42
                    versionId: 101
                    scanResults:
                    - scannerName: nova
                      scannerVersion: 1.2.0
                      result: pass
                      details:
                        rulesMatched: 0
                        rulesChecked: 47
                      scannedAt: '2026-01-16T02:00:00'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                default:
                  value:
                    detail: missing or invalid api key
        '404':
          description: No scan results for this version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                default:
                  value:
                    detail: no scan results for this version
      parameters:
      - name: skill_id
        in: path
        required: true
        description: Skill ID
        schema:
          type: integer
      - name: version_id
        in: path
        required: true
        description: Version ID
        schema:
          type: integer
  /mcp:
    get:
      operationId: listMcp
      summary: List MCP servers
      description: Returns a paginated list of MCP (Model Context Protocol) servers with scan status,
        stars, and metadata. Supports full-text search across name and description fields.
      tags:
      - mcp
      responses:
        '200':
          description: Paginated array of MCP server summaries with scan metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  mcpServers:
                    type: array
                    description: Array of MCP server objects
                    items:
                      $ref: '#/components/schemas/McpServerSummary'
                  total:
                    type: integer
                    description: Total matching MCP servers
                  page:
                    type: integer
                    description: Current page
                  limit:
                    type: integer
                    description: Page size
              examples:
                default:
                  summary: Provider-published example
                  value:
                    mcpServers:
                    - id: 9
                      name: filesystem
                      gitRepo: https://github.com/modelcontextprotocol/servers
                      serverPath: src/filesystem
                      description: Filesystem MCP server — read/write files within an allowed directory
                      sourceUrl: https://github.com/modelcontextprotocol/servers
                      stars: 4200
                      license: MIT
                      archived: false
                      latestVersionAt: '2026-02-10T08:00:00'
                      scanStatus: pass
                      latestScanAt: '2026-02-11T01:00:00'
                      fileSha256: 8f2a7e9d1c5b4f3e6a9d2c8b7e1f4a6d3c9b8e5f2a1d7c4b9e6f3a8d2c5b1e7f
                    total: 1
                    page: 1
                    limit: 50
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                default:
                  value:
                    detail: missing or invalid api key
      parameters:
      - name: q
        in: query
        required: false
        description: Search query — matches against MCP server name and description (ILIKE)
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: Sort field
        schema:
          type: string
          enum:
          - recent
          - name
          - status
          - stars
          - scanned
          default: recent
      - name: dir
        in: query
        required: false
        description: Sort direction. Defaults to DESC for recent/stars, ASC for name
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: status
        in: query
        required: false
        description: Filter by scan status
        schema:
          type: string
          enum:
          - dangerous
          - risky
          - safe
          - unscanned
      - name: source
        in: query
        required: false
        description: Filter by source URL (ILIKE match)
        schema:
          type: string
      - name: hash
        in: query
        required: false
        description: 'Filter by SHA-256 hash (64 hex characters) of the archived artifact bytes. Matches
          across versions: the artifact appears if any of its versions has this hash, even if the latest
          version was rebuilt with a different hash. The displayed row is the most recent version that
          matched. Composes with q, status, and source.'
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number (1-indexed)
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        required: false
        description: Results per page (1–200)
        schema:
          type: integer
          default: 50
  /mcp/{server_id}:
    get:
      operationId: getMcp
      summary: Get MCP server
      description: Returns full details for a single MCP server including version history, scan results
        for the selected version, and repository metadata.
      tags:
      - mcp
      responses:
        '200':
          description: Full MCP server object with nested versions and scan results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: MCP server ID
                  name:
                    type: string
                    description: Server name
                  gitRepo:
                    type: string
                    description: GitHub repository URL
                  serverPath:
                    type: string
                    description: Path to the server within the repo
                  description:
                    type:
                    - string
                    - 'null'
                    description: Server description
                  sourceUrl:
                    type:
                    - string
                    - 'null'
                    description: URL of the aggregator/source page where this server was discovered
                  scanStatus:
                    type: string
                    description: Aggregate scan status for the selected version
                  stars:
                    type:
                    - integer
                    - 'null'
                    description: GitHub stars
                  forks:
                    type:
                    - integer
                    - 'null'
                    description: GitHub forks
                  license:
                    type:
                    - string
                    - 'null'
                    description: SPDX license identifier
                  archived:
                    type:
                    - boolean
                    - 'null'
                    description: Whether the upstream GitHub repo is archived
                  repoCreatedAt:
                    type:
                    - string
                    - 'null'
                    description: ISO-8601 timestamp when the upstream repo was created
                  lastPushedAt:
                    type:
                    - string
                    - 'null'
                    description: ISO-8601 timestamp of the last push to the upstream repo
                  versions:
                    type: array
                    description: All tracked versions of this server, newest first
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Version ID — used as version_id in /mcp/:id/versions/:vid
                        commitHash:
                          type: string
                          description: Git commit SHA at this version
                        commitTimestamp:
                          type:
                          - string
                          - 'null'
                          description: ISO-8601 timestamp of the commit
                        scanSummary:
                          type: string
                          description: Aggregate scan status for this version
                        fileSha256:
                          type:
                          - string
                          - 'null'
                          description: SHA-256 hash (lowercase hex) of the archived artifact at this version.
                            null until the upstream pipeline computes it.
                  scanResults:
                    type: array
                    description: Scan results for the selected version
                    items:
                      type: object
                      properties:
                        scannerName:
                          type: string
                          description: Scanner identifier (e.g. 'nova')
                        scannerVersion:
                          type: string
                          description: Version of the scanner that produced this result
                        result:
                          type: string
                          description: Scan verdict (pass, warn, fail, error)
                        details:
                          type:
                          - object
                          - 'null'
                          description: Scanner-specific output (rules matched, files scanned, etc.)
                        scannedAt:
                          type:
                          - string
                          - 'null'
                          description: ISO-8601 timestamp when the scan ran
              examples:
                default:
                  summary: Provider-published example
                  value:
                    id: 9
                    name: filesystem
                    gitRepo: https://github.com/modelcontextprotocol/servers
                    serverPath: src/filesystem
                    description: Filesystem MCP server
                    sourceUrl: https://github.com/modelcontextprotocol/servers
                    scanStatus: pass
                    stars: 4200
                    forks: 380
                    license: MIT
                    archived: false
                    repoCreatedAt: '2025-04-01T00:00:00'
                    lastPushedAt: '2026-02-10T08:00:00'
                    versions:
                    - id: 201
                      commitHash: f4e5d6c
                      commitTimestamp: '2026-02-10T08:00:00'
                      scanSummary: pass
                      fileSha256: 8f2a7e9d1c5b4f3e6a9d2c8b7e1f4a6d3c9b8e5f2a1d7c4b9e6f3a8d2c5b1e7f
                    scanResults:
                    - scannerName: nova
                      scannerVersion: 1.2.0
                      result: pass
                      details:
                        rulesMatched: 0
                        rulesChecked: 47
                      scannedAt: '2026-02-11T01:00:00'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                default:
                  value:
                    detail: missing or invalid api key
        '404':
          description: MCP server not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                default:
                  value:
                    detail: mcp server not found
      parameters:
      - name: server_id
        in: path
        required: true
        description: MCP server ID
        schema:
          type: integer
      - name: version_id
        in: query
        required: false
        description: Select a specific version for scan results. Defaults to the latest version.
        schema:
          type: integer
  /mcp/{server_id}/versions/{version_id}:
    get:
      operationId: getMcpVersionScans
      summary: Get MCP version scan results
      description: Returns all scan results for a specific MCP server version. Useful for inspecting historical
        scan data across scanner versions.
      tags:
      - mcp
      responses:
        '200':
          description: Scan results for the specified version.
          content:
            application/json:
              schema:
                type: object
                properties:
                  serverId:
                    type: integer
                    description: MCP server ID
                  versionId:
                    type: integer
                    description: Version ID
                  scanResults:
                    type: array
                    description: Array of scan result objects
                    items:
                      type: object
                      properties:
                        scannerName:
                          type: string
                          description: Scanner identifier (e.g. 'nova')
                        scannerVersion:
                          type: string
                          description: Version of the scanner that produced this result
                        result:
                          type: string
                          description: Scan verdict (pass, warn, fail, error)
                        details:
                          type:
                          - object
                          - 'null'
                          description: Scanner-specific output (rules matched, files scanned, etc.)
                        scannedAt:
                          type:
                          - string
                          - 'null'
                          description: ISO-8601 timestamp when the scan ran
              examples:
                default:
                  summary: Provider-published example
                  value:
                    serverId: 9
                    versionId: 201
                    scanResults:
                    - scannerName: nova
                      scannerVersion: 1.2.0
                      result: pass
                      details:
                        rulesMatched: 0
                        rulesChecked: 47
                      scannedAt: '2026-02-11T01:00:00'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                default:
                  value:
                    detail: missing or invalid api key
        '404':
          description: No scan results for this version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                default:
                  value:
                    detail: no scan results for this version
      parameters:
      - name: server_id
        in: path
        required: true
        description: MCP server ID
        schema:
          type: integer
      - name: version_id
        in: path
        required: true
        description: Version ID
        schema:
          type: integer
  /extensions:
    get:
      operationId: listExtensions
      summary: List extensions
      description: Returns a paginated list of VSCode/IDE extensions with risk assessment data. Supports
        search across name, description, and publisher.
      tags:
      - extensions
      responses:
        '200':
          description: Paginated array of extension summaries with risk metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  extensions:
                    type: array
                    description: Array of extension objects
                    items:
                      $ref: '#/components/schemas/ExtensionSummary'
                  total:
                    type: integer
                    description: Total matching extensions
                  page:
                    type: integer
                    description: Current page
                  limit:
                    type: integer
                    description: Page size
              examples:
                default:
                  summary: Provider-published example
                  value:
                    extensions:
       

# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/knostic/refs/heads/main/openapi/knostic-agentmesh-openapi.yml