API Knowledge · Schema

API Knowledge Record

A single, agent-readable knowledge record about an API. Aggregates evidence from one or more sources (APIs.json, APIs.guru, RapidAPI, Postman, the provider's own portal, Naftiko Signals) into a structured, source-cited view of one API surface.

API KnowledgeKnowledge GraphsAPI DiscoveryAPI SearchCatalogsIndexesRegistriesRAGSemantic WebJSON-LDLLMsAI AgentsTopic

Properties

Name	Type	Description
id	string	Stable, lowercase, dash-delimited identifier for the API knowledge record. Should be globally unique within the knowledge layer. Convention: '{provider-slug}:{api-slug}'.
name	string	Human-readable name of the API.
description	string	One-paragraph description of what the API does, written from the provider's own materials.
humanURL	string	Canonical developer-portal URL for the API.
baseURL	string	Canonical request base URL for the API, if it has one.
provider	object	The organization or person operating the API.
capability	object	What the API can actually do. The agent-facing capability summary.
sources	array	Every place where this API is described or indexed. At least one entry is required.
sourceOfTruth	string	URL identifying the authoritative source for this API (typically the provider's own OpenAPI or developer portal). Used when sources conflict.
artifacts	object	Machine-readable artifacts that describe this API.
signals	array	External signals attached to this API (GitHub stars, hiring activity, changelog cadence, Naftiko Signal groups, etc.).
tags	array
created	string
modified	string
confidence	string	Aggregate confidence in the record, derived from source diversity and recency.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api-evangelist.github.io/knowledge/json-schema/knowledge-record-schema.json",
  "title": "API Knowledge Record",
  "description": "A single, agent-readable knowledge record about an API. Aggregates evidence from one or more sources (APIs.json, APIs.guru, RapidAPI, Postman, the provider's own portal, Naftiko Signals) into a structured, source-cited view of one API surface.",
  "type": "object",
  "required": ["id", "name", "provider", "capability", "sources"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Stable, lowercase, dash-delimited identifier for the API knowledge record. Should be globally unique within the knowledge layer. Convention: '{provider-slug}:{api-slug}'."
    },
    "name": {
      "type": "string",
      "description": "Human-readable name of the API."
    },
    "description": {
      "type": "string",
      "description": "One-paragraph description of what the API does, written from the provider's own materials."
    },
    "humanURL": {
      "type": "string",
      "format": "uri",
      "description": "Canonical developer-portal URL for the API."
    },
    "baseURL": {
      "type": "string",
      "format": "uri",
      "description": "Canonical request base URL for the API, if it has one."
    },
    "provider": {
      "type": "object",
      "description": "The organization or person operating the API.",
      "required": ["name"],
      "properties": {
        "name": { "type": "string" },
        "url": { "type": "string", "format": "uri" },
        "githubOrg": { "type": "string", "format": "uri" },
        "type": {
          "type": "string",
          "enum": ["Company", "Government", "Standard", "OpenSource", "Topic", "Individual"]
        }
      }
    },
    "capability": {
      "type": "object",
      "description": "What the API can actually do. The agent-facing capability summary.",
      "required": ["summary"],
      "properties": {
        "summary": {
          "type": "string",
          "description": "One-line capability summary, e.g. 'Send SMS messages globally', 'Query U.S. census tracts by FIPS code'."
        },
        "categories": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Coarse categories the API belongs to (e.g. 'Communications', 'Payments', 'AI/ML')."
        },
        "operations": {
          "type": "array",
          "description": "Optional list of named operations.",
          "items": {
            "type": "object",
            "required": ["name"],
            "properties": {
              "name": { "type": "string" },
              "method": {
                "type": "string",
                "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
              },
              "path": { "type": "string" },
              "description": { "type": "string" }
            }
          }
        }
      }
    },
    "sources": {
      "type": "array",
      "description": "Every place where this API is described or indexed. At least one entry is required.",
      "minItems": 1,
      "items": { "$ref": "#/$defs/source" }
    },
    "sourceOfTruth": {
      "type": "string",
      "format": "uri",
      "description": "URL identifying the authoritative source for this API (typically the provider's own OpenAPI or developer portal). Used when sources conflict."
    },
    "artifacts": {
      "type": "object",
      "description": "Machine-readable artifacts that describe this API.",
      "properties": {
        "openapi": {
          "type": "array",
          "items": { "type": "string", "format": "uri" }
        },
        "asyncapi": {
          "type": "array",
          "items": { "type": "string", "format": "uri" }
        },
        "jsonSchema": {
          "type": "array",
          "items": { "type": "string", "format": "uri" }
        },
        "jsonLd": {
          "type": "array",
          "items": { "type": "string", "format": "uri" }
        },
        "postmanCollection": {
          "type": "array",
          "items": { "type": "string", "format": "uri" }
        },
        "arazzo": {
          "type": "array",
          "items": { "type": "string", "format": "uri" }
        },
        "mcpServer": {
          "type": "array",
          "items": { "type": "string", "format": "uri" }
        },
        "llmsTxt": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "signals": {
      "type": "array",
      "description": "External signals attached to this API (GitHub stars, hiring activity, changelog cadence, Naftiko Signal groups, etc.).",
      "items": { "$ref": "#/$defs/signal" }
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    },
    "created": {
      "type": "string",
      "format": "date"
    },
    "modified": {
      "type": "string",
      "format": "date"
    },
    "confidence": {
      "type": "string",
      "enum": ["High", "Medium", "Low"],
      "description": "Aggregate confidence in the record, derived from source diversity and recency."
    }
  },
  "additionalProperties": false,
  "$defs": {
    "source": {
      "type": "object",
      "required": ["type", "url"],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "APIsJSON",
            "APIsGuru",
            "RapidAPI",
            "Postman",
            "ProviderPortal",
            "OpenAPI",
            "GitHubRepository",
            "GitHubOrganization",
            "DocumentationSite",
            "Changelog",
            "StatusPage",
            "Blog",
            "Marketplace",
            "MCPRegistry",
            "NaftikoSignals",
            "SchemaOrg",
            "LlmsTxt",
            "Other"
          ],
          "description": "Kind of source emitting this evidence."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL of the source page or file."
        },
        "evidence": { "$ref": "#/$defs/evidence" },
        "retrieved": {
          "type": "string",
          "format": "date-time",
          "description": "When this source was last verified."
        }
      }
    },
    "evidence": {
      "type": "object",
      "description": "A piece of cited evidence supporting a claim in the knowledge record.",
      "required": ["quote"],
      "properties": {
        "quote": {
          "type": "string",
          "description": "Verbatim quote from the source. Should be short enough to fall within fair use."
        },
        "claim": {
          "type": "string",
          "description": "The claim the quote supports (e.g. 'has public OpenAPI', 'rate limit 1000/hour', 'provider is a Linux Foundation member')."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL of the page the quote is from, if different from the parent source URL."
        }
      }
    },
    "signal": {
      "type": "object",
      "required": ["type", "value"],
      "properties": {
        "type": {
          "type": "string",
          "description": "Kind of signal (e.g. 'GitHubStars', 'JobPostingsLast30d', 'NaftikoSignalGroup', 'ChangelogCadenceDays')."
        },
        "value": {
          "description": "Signal value, untyped because signal types vary."
        },
        "source": {
          "type": "string",
          "format": "uri"
        },
        "observed": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}