{
  "openapi": "3.1.0",
  "info": {
    "title": "Top1031 Public Catalog API",
    "version": "1.0.0",
    "description": "Public name lookup for Top1031 Trust and Sponsor records. Follow each result's href for source citations, dates, disclosures, gated-surface presentation, and the complete record context. This API does not provide investment, tax, or legal advice and does not confirm that an Offering remains available. The current major version is 1. Omitting X-API-Version selects version 1. Version 1 changes are additive. If a major version is deprecated, Top1031 will announce it in the developer documentation and this description at least 180 days before retirement. During that window, affected responses will include the HTTP Deprecation and Sunset headers; retirement will not occur before the date in Sunset."
  },
  "servers": [
    {
      "url": "https://www.top1031.com"
    }
  ],
  "paths": {
    "/api/catalog/search/": {
      "get": {
        "operationId": "searchTop1031Catalog",
        "summary": "Find public Top1031 records by name",
        "description": "Returns up to ten public Trust and Sponsor matches. Use this endpoint for name lookup, then follow href for the complete source-linked record.",
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "required": false,
            "description": "Part or all of a Trust marketing title or Sponsor display name. When supplied, use 2–80 characters. Omit for a reachability check that returns an empty result set.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 80
            },
            "example": "nexpoint"
          },
          {
            "in": "query",
            "name": "scope",
            "required": false,
            "description": "Restrict results to Active Trusts. Omit to include public Historical Trusts and Sponsors.",
            "schema": {
              "type": "string",
              "enum": [
                "active-offerings"
              ]
            }
          },
          {
            "in": "header",
            "name": "X-API-Version",
            "required": false,
            "description": "Pins the API major version. Omit to use the current major version, 1.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ],
              "default": "1"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching public catalog records",
            "headers": {
              "X-API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogSearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Unsupported API version or invalid query parameter",
            "headers": {
              "X-API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Catalog search is temporarily unavailable",
            "headers": {
              "X-API-Version": {
                "$ref": "#/components/headers/ApiVersion"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "ApiVersion": {
        "description": "API major version used for the response.",
        "schema": {
          "type": "string",
          "const": "1"
        }
      },
      "Deprecation": {
        "description": "Present only after this API major version enters its announced deprecation window; contains the Structured Field Date when deprecation began.",
        "schema": {
          "type": "string",
          "example": "@1819756800"
        }
      },
      "Sunset": {
        "description": "Present only after this API major version is deprecated; contains the HTTP date after which the version may be retired, at least 180 days after notice.",
        "schema": {
          "type": "string",
          "example": "Thu, 31 Aug 2028 23:59:59 GMT"
        }
      }
    },
    "schemas": {
      "ApiErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ApiError"
          }
        }
      },
      "ApiError": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "catalog_unavailable",
              "invalid_parameter",
              "unsupported_api_version"
            ]
          },
          "message": {
            "type": "string"
          },
          "parameter": {
            "type": "string",
            "enum": [
              "q",
              "scope",
              "X-API-Version"
            ]
          }
        }
      },
      "CatalogSearchResponse": {
        "type": "object",
        "required": [
          "results"
        ],
        "properties": {
          "results": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/CatalogSearchResult"
            }
          }
        }
      },
      "CatalogSearchResult": {
        "type": "object",
        "required": [
          "href",
          "id",
          "kind",
          "meta",
          "title"
        ],
        "properties": {
          "href": {
            "type": "string",
            "description": "Canonical path to the complete public Top1031 record."
          },
          "id": {
            "type": "integer",
            "description": "Catalog record identifier. Use href as the canonical public identity."
          },
          "kind": {
            "type": "string",
            "enum": [
              "trust",
              "sponsor"
            ]
          },
          "meta": {
            "type": "string",
            "description": "Short catalog context such as Asset Bucket and location or Sponsor Program count."
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "description": "Trust marketing title or Sponsor display name."
          }
        }
      }
    }
  }
}