{
  "openapi": "3.1.0",
  "info": {
    "title": "XframeworkID Registry API",
    "description": "Query the XframeworkID registry of labelled bond disclosure documents \u2014 green bond frameworks, second-party opinions (SPOs), impact reports, assurance reports, certifications, EU GBS reviews, and academic research. All data is open and free to use. Documents are identified by permanent XFIDs (e.g. XFA3B7K2M9), issuers by slug (e.g. manulife-financial-corporation), and analysts by XPID.",
    "version": "1.0.0",
    "contact": {
      "name": "XframeworkID",
      "url": "https://xframework.id",
      "email": "ihoward@vectorbravo.com"
    }
  },
  "servers": [
    {
      "url": "https://xframework.id",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/registry/search": {
      "get": {
        "operationId": "searchDocuments",
        "summary": "Search the document registry",
        "description": "Search across ~13,000 labelled bond disclosure documents by keyword, type, year, and country. Returns matching documents with their XFID, title, issuer, type, year, and permanent URL.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Free-text search across document titles and issuer names (e.g. 'Manulife', 'green bond framework', 'Sustainalytics')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Filter by document type",
            "schema": {
              "type": "string",
              "enum": [
                "FRAMEWORK",
                "SPO",
                "IMPACT",
                "ASSURANCE",
                "CERTIFICATION",
                "EUGBS_REVIEW",
                "RESEARCH",
                "INVESTOR_FRAMEWORK",
                "BANK_FRAMEWORK"
              ]
            }
          },
          {
            "name": "year",
            "in": "query",
            "description": "Filter by issuance or publication year (e.g. 2024)",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "country",
            "in": "query",
            "description": "Filter by 2-letter ISO country code (e.g. CA, DE, NL)",
            "schema": {
              "type": "string",
              "maxLength": 2
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum results to return (default 20, max 100)",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DocumentSummary"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "query": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/registry/{xfid}": {
      "get": {
        "operationId": "getDocument",
        "summary": "Get a document by XFID",
        "description": "Resolve any XFID to its full registry record \u2014 title, issuer, type, year, source URL, analysts, related documents (framework \u2194 SPO \u2194 impact \u2194 assurance), and linked bond ISINs. The XFID is a permanent content-based identifier (e.g. XFA3B7K2M9 or XF-A3B7K2M-9).",
        "parameters": [
          {
            "name": "xfid",
            "in": "path",
            "required": true,
            "description": "Document XFID, with or without dashes (e.g. XFA3B7K2M9)",
            "schema": {
              "type": "string",
              "pattern": "^XF[A-Z0-9-]{8,11}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Document detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentDetail"
                }
              }
            }
          },
          "404": {
            "description": "Document not found"
          }
        }
      }
    },
    "/api/registry/issuer/{slug}": {
      "get": {
        "operationId": "getIssuer",
        "summary": "Get an issuer's profile and all their documents",
        "description": "Returns an issuer's full registry profile \u2014 name, country, sector \u2014 and all their associated documents across all types (frameworks, SPOs, impact reports, assurance, certifications). Use searchDocuments first if you don't know the exact slug.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "URL-safe issuer identifier (e.g. manulife-financial-corporation, iberdrola, deutsche-bank-ag)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Issuer profile with documents",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IssuerProfile"
                }
              }
            }
          },
          "404": {
            "description": "Issuer not found"
          }
        }
      }
    },
    "/api/registry/person/{xpid}": {
      "get": {
        "operationId": "getAnalyst",
        "summary": "Get an analyst or researcher profile by XPID",
        "description": "Returns a person's profile \u2014 name, organisation, role \u2014 and all documents they appear in. Useful for looking up SPO analysts, CBI verifiers, or academic authors. XPID format: XP followed by 8 alphanumeric characters.",
        "parameters": [
          {
            "name": "xpid",
            "in": "path",
            "required": true,
            "description": "Person identifier (e.g. XPKMSXUDSB)",
            "schema": {
              "type": "string",
              "pattern": "^XP[A-Z0-9]{8}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Person profile with linked documents",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonProfile"
                }
              }
            }
          },
          "404": {
            "description": "Person not found"
          }
        }
      }
    },
    "/api/registry/organization/{orgId}": {
      "get": {
        "operationId": "getOrganization",
        "summary": "Get an assessment provider or investor organisation profile",
        "description": "Returns profile for organisations in the registry \u2014 SPO providers (Sustainalytics, ISS ESG, Sustainable Fitch), CBI verifiers, institutional investors. Includes their analysts and documents.",
        "parameters": [
          {
            "name": "orgId",
            "in": "path",
            "required": true,
            "description": "Organisation identifier (e.g. XO7KN83X7F)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Organisation profile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgProfile"
                }
              }
            }
          },
          "404": {
            "description": "Organisation not found"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DocumentSummary": {
        "type": "object",
        "properties": {
          "xfid": {
            "type": "string",
            "description": "Permanent document identifier (e.g. XFA3B7K2M9)"
          },
          "title": {
            "type": "string"
          },
          "documentType": {
            "type": "string",
            "description": "FRAMEWORK, SPO, IMPACT, ASSURANCE, CERTIFICATION, EUGBS_REVIEW, RESEARCH"
          },
          "issuerName": {
            "type": "string"
          },
          "issuerId": {
            "type": "string",
            "description": "Issuer slug for use with getIssuer"
          },
          "issueYear": {
            "type": "integer"
          },
          "country": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Permanent page URL: https://xframework.id/{xfid}"
          },
          "sourceUrl": {
            "type": "string",
            "description": "Original source document URL (may no longer be live)"
          }
        }
      },
      "DocumentDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/DocumentSummary"
          },
          {
            "type": "object",
            "properties": {
              "relatedDocuments": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "xfid": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "documentType": {
                      "type": "string"
                    },
                    "relationshipType": {
                      "type": "string",
                      "description": "spo_of, impact_of, assurance_of, supersedes, discusses"
                    }
                  }
                }
              },
              "persons": {
                "type": "array",
                "description": "Analysts or authors cited in the document",
                "items": {
                  "type": "object",
                  "properties": {
                    "xpid": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "org": {
                      "type": "string"
                    },
                    "role": {
                      "type": "string"
                    }
                  }
                }
              },
              "isins": {
                "type": "array",
                "description": "Bond ISINs linked to this document",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        ]
      },
      "IssuerProfile": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "sector": {
            "type": "string"
          },
          "primaryDomain": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Issuer page: https://xframework.id/registry/issuers/{id}"
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DocumentSummary"
            }
          }
        }
      },
      "PersonProfile": {
        "type": "object",
        "properties": {
          "xpid": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "organisation": {
            "type": "string"
          },
          "primaryRole": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DocumentSummary"
            }
          }
        }
      },
      "OrgProfile": {
        "type": "object",
        "properties": {
          "orgId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "orgType": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "analysts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PersonProfile"
            }
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DocumentSummary"
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Dataset downloads (CC BY 4.0, DOI 10.5281/zenodo.21297903), data dictionary and API guide",
    "url": "https://xframework.id/data"
  }
}