APIs.json

aid: apis-json
name: APIs.json
description: >-
  APIs.json is an open, machine-readable specification that API providers can
  use to describe their API operations, similar to how websites use sitemap.xml.
  The format provides a lightweight means for individuals and organizations to
  document the location of their APIs, associated descriptions, human and
  machine-readable specifications, and ancillary information such as licensing,
  maintainers, and terms of service. It was created by Kin Lane and Steven
  Willmott in May 2014 and is maintained as an open IETF-style draft. The
  current stable version is 0.19, published in November 2024. APIs.json files
  can be placed at the root of any domain as /apis.json or /apis.yml for
  automated discovery. The specification defines root-level fields (name,
  description, url, apis, common), API-level fields (aid, humanURL, baseURL,
  tags, properties), and a comprehensive list of property types covering
  documentation, authentication, licensing, support, and governance. It is the
  foundation for the APIs.io search engine and API Commons initiative.
type: Index
image: https://kinlane-productions.s3.amazonaws.com/apis-json/apis-json-logo.jpg
tags:
  - API Aggregation
  - API Cataloging
  - API Commons
  - API Discovery
  - API Governance
  - API Operations
  - Machine Readable
  - Specification
  - Standard
url: >-
  https://raw.githubusercontent.com/api-evangelist/apis-json/refs/heads/main/apis.yml
created: '2026-03-26'
modified: '2026-04-19'
specificationVersion: '0.19'
apis:
  - aid: apis-json:apis-json-specification
    name: APIs.json Specification
    description: >-
      The APIs.json specification defines a machine-readable JSON or YAML format
      for describing API operations. Unlike OpenAPI which describes the technical
      interface of a single API, APIs.json describes the surrounding operations
      of one or more APIs — documentation, authentication, pricing, terms of
      service, support, and other properties. Created by Kin Lane and Steven
      Willmott in May 2014, the specification is maintained as an informal IETF
      draft at apisjson.org. The current stable version is 0.19, published
      November 6, 2024. APIs.json files are placed at the domain root as
      /apis.json or /apis.yml for automated discovery by robots and search
      engines.
    humanURL: https://apisjson.org
    tags:
      - API Description
      - API Discovery
      - API Operations
      - Machine Readable
      - Specification
      - Standard
    properties:
      - type: Documentation
        url: https://apisjson.org/schema/
      - type: Specification
        url: >-
          https://raw.githubusercontent.com/api-evangelist/apis-json/refs/heads/main/spec/apisjson_0.19.txt
      - type: JSONSchema
        url: >-
          https://raw.githubusercontent.com/api-evangelist/apis-json/refs/heads/main/json-schema/apis-json-schema-0.19.yaml
        title: Schema v0.19
      - type: JSONSchema
        url: >-
          https://raw.githubusercontent.com/api-evangelist/apis-json/refs/heads/main/json-schema/apis-json-schema-0.18.yaml
        title: Schema v0.18
      - type: JSONSchema
        url: >-
          https://raw.githubusercontent.com/api-evangelist/apis-json/refs/heads/main/json-schema/apis-json-schema-0.17.yaml
        title: Schema v0.17
      - type: JSONSchema
        url: >-
          https://raw.githubusercontent.com/api-evangelist/apis-json/refs/heads/main/json-schema/apis-json-schema-0.20.yaml
        title: Schema v0.20 (Draft)
common:
  - type: Website
    url: https://apisjson.org
  - type: Properties
    url: https://apisjson.org/properties/
  - type: Blog
    url: https://apisjson.org/blog/
  - type: GitHubOrganization
    url: https://github.com/apis-json
  - type: GitHubRepository
    url: https://github.com/apis-json/api-json
    title: Specification Repository
  - type: GitHubRepository
    url: https://github.com/apis-json/apis-json-website
    title: Website
  - type: GitHubRepository
    url: https://github.com/apis-json/artisanal
    title: Artisanal APIs.json Examples
  - type: GitHubRepository
    url: https://github.com/apis-json/backstage
    title: Backstage Integration
  - type: Support
    url: https://github.com/apis-json/api-json/issues
  - type: SpectralRules
    url: >-
      https://raw.githubusercontent.com/api-evangelist/apis-json/refs/heads/main/rules/apis-json-spectral-rules.yml
  - type: Vocabulary
    url: >-
      https://raw.githubusercontent.com/api-evangelist/apis-json/refs/heads/main/vocabulary/apis-json-vocabulary.yaml
  - type: Features
    data:
      - name: Machine-Readable API Operations
        description: >-
          Provides a machine-readable format for documenting API operations
          beyond just the technical interface, covering documentation, pricing,
          authentication, terms of service, support, and governance.
      - name: Domain Root Discovery
        description: >-
          APIs.json files can be placed at /apis.json or /apis.yml at the root
          of any domain, enabling automated discovery by search engines and
          robots without prior knowledge of the API provider.
      - name: Property Type System
        description: >-
          Defines a comprehensive enumerated set of property types (OpenAPI,
          Documentation, Authentication, Pricing, Support, etc.) enabling
          consistent machine-readable indexing of API operations.
      - name: Federation via Include
        description: >-
          Supports federated API directories through include references, allowing
          a root APIs.json to reference other APIs.json files on different
          servers or domains.
      - name: Multiple API Collections
        description: >-
          A single APIs.json file can document multiple APIs in the apis array,
          with shared properties in the common section, enabling organization-wide
          API catalogs.
      - name: Authority and Non-Authority
        description: >-
          Defines authoritative (same DNS domain) and non-authoritative entries,
          with conflict resolution rules giving priority to the most specific
          authoritative entry.
      - name: Overlay Support
        description: >-
          Supports overlay specifications that can modify or extend existing
          APIs.json entries, enabling provider-agnostic enrichment of API metadata.
      - name: Version History
        description: >-
          Maintained as a versioned specification from 0.11 through current 0.19,
          with full version history and diff comparisons available on GitHub and
          apisjson.org.
  - type: UseCases
    data:
      - name: API Discovery
        description: >-
          API providers publish APIs.json files at their domain root so that
          search engines like APIs.io can automatically discover and index all
          their APIs without manual submission.
      - name: API Governance
        description: >-
          Platform teams use APIs.json as a canonical machine-readable index
          of their API portfolio, enabling automated compliance checking of
          required operational properties like terms of service and authentication.
      - name: API Portal Generation
        description: >-
          Developer portals can be automatically generated from APIs.json files
          by reading the properties array and presenting documentation, OpenAPI
          specs, getting started guides, and other resources.
      - name: API Commons Participation
        description: >-
          Organizations publish APIs.json files to participate in the API Commons
          initiative, making their APIs discoverable and accessible to a wider
          developer community.
      - name: Internal API Catalog
        description: >-
          Enterprises use APIs.json as the foundation for internal API catalogs,
          enabling discoverability of internal, partner, and public APIs using
          a consistent machine-readable format.
      - name: Backstage Integration
        description: >-
          Teams use the APIs.json Backstage integration to import API metadata
          from APIs.json files into Spotify Backstage for internal developer
          portal use.
  - type: Integrations
    data:
      - name: APIs.io
        description: >-
          The APIs.io search engine is built entirely on the APIs.json
          specification, indexing submitted APIs.json files to power its
          API discovery and search capabilities.
      - name: API Commons
        description: >-
          API Commons uses APIs.json as its core metadata format for documenting
          API operations across the open API ecosystem.
      - name: OpenAPI
        description: >-
          APIs.json references OpenAPI specifications as a core property type,
          linking machine-readable API interface descriptions to their operations
          metadata.
      - name: Backstage
        description: >-
          APIs.json files can be imported into Spotify Backstage using the
          apis-json/backstage integration tool for enterprise developer portal use.
      - name: Spectral
        description: >-
          Spectral rulesets can validate APIs.json files against the specification
          schema and enforce organizational governance rules for API operations.
      - name: AsyncAPI
        description: >-
          APIs.json supports AsyncAPI as a property type, allowing event-driven
          and message-based APIs to be documented alongside REST APIs in a single
          APIs.json file.
maintainers:
  - FN: Kin Lane
    email: [email protected]