Knostic
Knostic skills API

AI agent skills (SKILL.md) discovered and scanned by AgentMesh
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  title: Knostic AgentMesh extensions skills 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
security:
- bearerAuth: []
tags:
- name: skills
  description: AI agent skills (SKILL.md) discovered and scanned by AgentMesh
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
components:
  schemas:
    SkillSummary:
      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
          description: Skill description
        sourceUrl:
          type: string
          description: URL of the aggregator/source page where this skill was discovered
        stars:
          type: integer
          description: GitHub stars
        license:
          type: string
          description: SPDX license identifier
        archived:
          type: boolean
          description: Whether the upstream GitHub repo is archived
        latestVersionAt:
          type: string
        scanStatus:
          type: string
          description: Aggregate scan status for the selected version
        latestScanAt:
          type: string
        contributor:
          type: string
          description: GitHub login of the most recent committer, or null if unknown
        fileSha256:
          type: string
          description: SHA-256 hash (lowercase hex) of the archived extension artifact. null until the upstream pipeline computes it.
    Error:
      type: object
      description: AgentMesh error envelope.
      properties:
        detail:
          type: string
          description: Human-readable error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'AgentMesh API key issued from the console (POST /api/console/keys), sent as `Authorization: Bearer <api_key>`. Read endpoints also serve anonymous callers at a reduced tier.'
Knostic skills API

Documentation

Specifications

Other Resources

OpenAPI Specification
