{
  "openapi": "3.1.0",
  "info": {
    "title": "CPSP-PMDF Public REST API",
    "version": "1.0.0",
    "description": "Read-only, versioned public API for CPSP-PMDF identity and discovery metadata. The REST surface is intentionally limited to public information. Errors use RFC 9457 application/problem+json. The current major version is exposed under /api/v1; breaking changes require a new major URL version."
  },
  "servers": [
    {
      "url": "https://cpsp-pmdf.vercel.app",
      "description": "Canonical CPSP-PMDF production origin"
    }
  ],
  "externalDocs": {
    "description": "CPSP-PMDF developer resources, versioning, errors and deprecation policy",
    "url": "https://cpsp-pmdf.vercel.app/developers"
  },
  "tags": [
    {
      "name": "Public API",
      "description": "Public, read-only CPSP-PMDF identity, discovery and policy resources."
    }
  ],
  "x-api-versioning": {
    "strategy": "URL path versioning",
    "current": "v1",
    "breakingChanges": "A breaking change requires a new major path such as /api/v2.",
    "deprecation": "When a version enters deprecation, responses use the Deprecation header defined by RFC 9745. If retirement is scheduled, responses also use the Sunset header defined by RFC 8594. The default public notice window is at least 90 days except urgent security, legal or privacy removals."
  },
  "x-mcp": {
    "endpoint": "https://cpsp-pmdf.vercel.app/.well-known/mcp",
    "protocolVersion": "2026-07-28",
    "serverCard": "https://cpsp-pmdf.vercel.app/.well-known/mcp/server-card.json",
    "description": "Separate public informational MCP surface using Streamable HTTP."
  },
  "paths": {
    "/api/v1": {
      "get": {
        "operationId": "getPublicApiIndex",
        "tags": [
          "Public API"
        ],
        "summary": "Get the CPSP-PMDF public API index",
        "description": "Returns the active public API version, documentation links and canonical URLs for the other versioned public resources.",
        "responses": {
          "200": {
            "description": "Public API index.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiIndex"
                }
              }
            }
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/api/v1/site": {
      "get": {
        "operationId": "getCpspPmdfSiteOverview",
        "tags": [
          "Public API"
        ],
        "summary": "Get the CPSP-PMDF public site identity",
        "description": "Returns public identity and institutional contact metadata only. Authenticated records, operational data and internal permissions are never exposed by this endpoint.",
        "responses": {
          "200": {
            "description": "CPSP-PMDF public site identity.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteOverview"
                }
              }
            }
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/api/v1/resources": {
      "get": {
        "operationId": "listCpspPmdfPublicResources",
        "tags": [
          "Public API"
        ],
        "summary": "List CPSP-PMDF public machine-readable resources",
        "description": "Lists the canonical public developer, agent-discovery and trust resources published by CPSP-PMDF, including OpenAPI, llms.txt, MCP, sitemap and Markdown.",
        "responses": {
          "200": {
            "description": "Public resource catalog.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicResources"
                }
              }
            }
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/api/v1/policies": {
      "get": {
        "operationId": "getCpspPmdfPublicApiPolicies",
        "tags": [
          "Public API"
        ],
        "summary": "Get public API versioning, deprecation, error and rate-limit policies",
        "description": "Returns the machine-readable compatibility contract for versioning, RFC 9457 errors, deprecation signaling and public API throttling.",
        "responses": {
          "200": {
            "description": "Public API compatibility policies.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiPolicies"
                }
              }
            }
          },
          "406": {
            "$ref": "#/components/responses/NotAcceptable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "ApiVersion": {
        "description": "Active major public API version.",
        "schema": {
          "type": "string",
          "const": "1"
        }
      },
      "RateLimitPolicy": {
        "description": "Current RateLimit policy using the structured-field convention from the IETF HTTPAPI RateLimit work.",
        "schema": {
          "type": "string",
          "example": "\"public\";q=60;w=60"
        }
      },
      "RateLimit": {
        "description": "Current remaining quota and reset interval for the active rate-limit policy.",
        "schema": {
          "type": "string",
          "example": "\"public\";r=59;t=60"
        }
      },
      "RateLimitLimit": {
        "description": "Compatibility field: maximum request quota for the current window.",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "example": 60
        }
      },
      "RateLimitRemaining": {
        "description": "Compatibility field: request quota remaining in the current window.",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "example": 59
        }
      },
      "RateLimitReset": {
        "description": "Compatibility field: seconds until the current quota window resets.",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "example": 60
        }
      },
      "RetryAfter": {
        "description": "Seconds the client should wait before retrying a request rejected with HTTP 429.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "example": 42
        }
      },
      "Deprecation": {
        "description": "RFC 9745 Deprecation header. Omitted while v1 is active; when present it carries the deprecation timestamp.",
        "schema": {
          "type": "string",
          "example": "@1782864000"
        }
      },
      "Sunset": {
        "description": "RFC 8594 Sunset header. Omitted unless a deprecated API version has a scheduled retirement date.",
        "schema": {
          "type": "string",
          "example": "Wed, 30 Sep 2026 23:59:59 GMT"
        }
      }
    },
    "responses": {
      "NotAcceptable": {
        "description": "The requested representation is not available.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/ApiVersion"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitLimit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitRemaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitReset"
          },
          "Deprecation": {
            "$ref": "#/components/headers/Deprecation"
          },
          "Sunset": {
            "$ref": "#/components/headers/Sunset"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Public API request quota exceeded.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/ApiVersion"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitLimit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitRemaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitReset"
          },
          "Deprecation": {
            "$ref": "#/components/headers/Deprecation"
          },
          "Sunset": {
            "$ref": "#/components/headers/Sunset"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Unexpected public API failure.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/ApiVersion"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitLimit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitRemaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitReset"
          },
          "Deprecation": {
            "$ref": "#/components/headers/Deprecation"
          },
          "Sunset": {
            "$ref": "#/components/headers/Sunset"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "NotFound": {
        "description": "Public API resource not found.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/ApiVersion"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitLimit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitRemaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitReset"
          },
          "Deprecation": {
            "$ref": "#/components/headers/Deprecation"
          },
          "Sunset": {
            "$ref": "#/components/headers/Sunset"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "The public API is read-only and the HTTP method is not supported.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/ApiVersion"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitLimit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitRemaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitReset"
          },
          "Deprecation": {
            "$ref": "#/components/headers/Deprecation"
          },
          "Sunset": {
            "$ref": "#/components/headers/Sunset"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      }
    },
    "schemas": {
      "PublicApiIndex": {
        "type": "object",
        "required": [
          "name",
          "version",
          "status",
          "documentation",
          "openapi",
          "endpoints"
        ],
        "properties": {
          "name": {
            "type": "string",
            "const": "CPSP-PMDF Public REST API"
          },
          "version": {
            "type": "string",
            "const": "v1"
          },
          "status": {
            "type": "string",
            "enum": [
              "stable"
            ]
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          },
          "openapi": {
            "type": "string",
            "format": "uri"
          },
          "endpoints": {
            "type": "object",
            "required": [
              "site",
              "resources",
              "policies"
            ],
            "properties": {
              "site": {
                "type": "string",
                "format": "uri"
              },
              "resources": {
                "type": "string",
                "format": "uri"
              },
              "policies": {
                "type": "string",
                "format": "uri"
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "SiteOverview": {
        "type": "object",
        "required": [
          "name",
          "description",
          "canonicalUrl",
          "organization",
          "publicSurfaceOnly",
          "authenticatedDataExposed"
        ],
        "properties": {
          "name": {
            "type": "string",
            "const": "CPSP-PMDF"
          },
          "description": {
            "type": "string"
          },
          "canonicalUrl": {
            "type": "string",
            "format": "uri"
          },
          "organization": {
            "type": "object",
            "required": [
              "name",
              "alternateName",
              "parentOrganization",
              "email",
              "telephone",
              "address"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "alternateName": {
                "type": "string"
              },
              "parentOrganization": {
                "type": "string"
              },
              "email": {
                "type": "string",
                "format": "email"
              },
              "telephone": {
                "type": "string"
              },
              "address": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "publicSurfaceOnly": {
            "type": "boolean",
            "const": true
          },
          "authenticatedDataExposed": {
            "type": "boolean",
            "const": false
          }
        },
        "additionalProperties": false
      },
      "PublicResource": {
        "type": "object",
        "required": [
          "name",
          "url",
          "mediaType",
          "description"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "mediaType": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "PublicResources": {
        "type": "object",
        "required": [
          "resources"
        ],
        "properties": {
          "resources": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/PublicResource"
            }
          }
        },
        "additionalProperties": false
      },
      "ApiPolicies": {
        "type": "object",
        "required": [
          "versioning",
          "deprecation",
          "errors",
          "rateLimit"
        ],
        "properties": {
          "versioning": {
            "type": "object",
            "required": [
              "strategy",
              "currentVersion",
              "basePath",
              "compatibilityRule"
            ],
            "properties": {
              "strategy": {
                "type": "string"
              },
              "currentVersion": {
                "type": "string",
                "const": "v1"
              },
              "basePath": {
                "type": "string",
                "const": "/api/v1"
              },
              "compatibilityRule": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "deprecation": {
            "type": "object",
            "required": [
              "deprecated",
              "minimumNoticeDays",
              "signals",
              "emergencyException"
            ],
            "properties": {
              "deprecated": {
                "type": "boolean"
              },
              "minimumNoticeDays": {
                "type": "integer",
                "minimum": 0
              },
              "signals": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "emergencyException": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "errors": {
            "type": "object",
            "required": [
              "mediaType",
              "standard",
              "extensions"
            ],
            "properties": {
              "mediaType": {
                "type": "string",
                "const": "application/problem+json"
              },
              "standard": {
                "type": "string",
                "const": "RFC 9457"
              },
              "extensions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "additionalProperties": false
          },
          "rateLimit": {
            "type": "object",
            "required": [
              "quota",
              "windowSeconds",
              "scope",
              "headers"
            ],
            "properties": {
              "quota": {
                "type": "integer",
                "minimum": 1
              },
              "windowSeconds": {
                "type": "integer",
                "minimum": 1
              },
              "scope": {
                "type": "string"
              },
              "headers": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "ProblemDetails": {
        "type": "object",
        "description": "RFC 9457 Problem Details object with stable CPSP-PMDF extensions for machine-readable error handling.",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "instance",
          "code",
          "hint"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri-reference"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599
          },
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string",
            "format": "uri-reference"
          },
          "code": {
            "type": "string",
            "enum": [
              "RESOURCE_NOT_FOUND",
              "METHOD_NOT_ALLOWED",
              "NOT_ACCEPTABLE",
              "RATE_LIMIT_EXCEEDED",
              "INTERNAL_ERROR"
            ]
          },
          "hint": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    }
  }
}