{
  "openapi": "3.1.0",
  "info": {
    "title": "Medcrypt website API",
    "version": "1.0.0",
    "summary": "Public, read-only machine-readable endpoints of the Medcrypt website.",
    "contact": {
      "name": "Medcrypt developer portal",
      "url": "https://www.medcrypt.com/developers",
      "email": "info@medcrypt.com"
    },
    "description": "Describes the discovery endpoints of the Medcrypt marketing website: the API index, site index for AI assistants (llms.txt), sitemap, robots policy, and RFC 9727 API catalog.\n\nAll endpoints are unauthenticated and read-only (GET/HEAD). Errors under `/api` are returned as RFC 9457 problem details (`application/problem+json`) with `code`, `hint`, and `docs` extension members.\n\nAny unknown path returns HTTP 404. Send `Accept: text/markdown` to receive a Markdown error body, or `Accept: application/json` to receive problem details.\n\n## Versioning and deprecation\n\n- The API is versioned in the URL path. The current version is v1, at `/api/v1`. Pin that path for stable integrations.\n- `/api` is an unversioned alias that always serves the latest version; its `Content-Location` header names the versioned path it resolved to.\n- Within a version, changes are additive only: new fields or resources may appear, and existing ones are not removed or changed in meaning. Ignore fields you don't recognize.\n- A breaking change ships as a new version. The old version then responds with a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) at least 180 days before it stops responding.\n\n## Rate limits\n\n- Every `/api` response carries `RateLimit-Policy` and `RateLimit` headers (IETF HTTPAPI RateLimit header fields). The quota is 60 requests per 60 seconds per client.\n- `RateLimit` reports `r` (requests remaining) and `t` (seconds until the window resets). Slow down as `r` approaches 0.\n- Past the quota, the API returns `429 Too Many Requests` as `application/problem+json` with a `Retry-After` header (seconds). Wait that long before retrying."
  },
  "servers": [
    {
      "url": "https://www.medcrypt.com"
    }
  ],
  "security": [],
  "externalDocs": {
    "description": "Medcrypt developer portal",
    "url": "https://www.medcrypt.com/developers"
  },
  "tags": [
    {
      "name": "api",
      "description": "JSON API index"
    },
    {
      "name": "discovery",
      "description": "Discovery and crawler files"
    }
  ],
  "paths": {
    "/api/v1": {
      "get": {
        "operationId": "getApiIndexV1",
        "tags": [
          "api"
        ],
        "summary": "List machine-readable resources (v1)",
        "description": "Versioned API index. Pin this path for stable integrations.",
        "responses": {
          "200": {
            "description": "API index",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Deprecation": {
                "$ref": "#/components/headers/Deprecation"
              },
              "Sunset": {
                "$ref": "#/components/headers/Sunset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiIndex"
                }
              }
            }
          },
          "404": {
            "description": "Unknown path. RFC 9457 problem details with `code: not_found`.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Write method on the read-only API. `code: method_not_allowed`; `Allow` lists GET, HEAD.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Allow": {
                "$ref": "#/components/headers/Allow"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (`code: rate_limited`). Wait `Retry-After` seconds before retrying.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error. `code: internal_error`; retry later.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api": {
      "get": {
        "operationId": "getApiIndex",
        "tags": [
          "api"
        ],
        "summary": "List machine-readable resources (latest version)",
        "description": "Unversioned alias that always serves the latest version, currently `/api/v1`. `Content-Location` names the versioned path.",
        "responses": {
          "200": {
            "description": "API index",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Content-Location": {
                "$ref": "#/components/headers/ContentLocation"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiIndex"
                }
              }
            }
          },
          "404": {
            "description": "Unknown path. RFC 9457 problem details with `code: not_found`.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Write method on the read-only API. `code: method_not_allowed`; `Allow` lists GET, HEAD.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Allow": {
                "$ref": "#/components/headers/Allow"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (`code: rate_limited`). Wait `Retry-After` seconds before retrying.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error. `code: internal_error`; retry later.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiDocument",
        "tags": [
          "discovery"
        ],
        "summary": "This OpenAPI description",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Problem details for `Accept: application/json`, Markdown for `Accept: text/markdown`, HTML otherwise.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/api-catalog": {
      "get": {
        "operationId": "getApiCatalog",
        "tags": [
          "discovery"
        ],
        "summary": "RFC 9727 API catalog",
        "responses": {
          "200": {
            "description": "Linkset (RFC 9264) listing this site's APIs",
            "content": {
              "application/linkset+json; profile=\"https://www.rfc-editor.org/info/rfc9727\"": {
                "schema": {
                  "$ref": "#/components/schemas/Linkset"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Problem details for `Accept: application/json`, Markdown for `Accept: text/markdown`, HTML otherwise.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "tags": [
          "discovery"
        ],
        "summary": "Site index for AI assistants (llms.txt)",
        "responses": {
          "200": {
            "description": "Markdown index of the site's key pages",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Problem details for `Accept: application/json`, Markdown for `Accept: text/markdown`, HTML otherwise.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/robots.txt": {
      "get": {
        "operationId": "getRobotsTxt",
        "tags": [
          "discovery"
        ],
        "summary": "Crawler permissions",
        "responses": {
          "200": {
            "description": "robots.txt",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Problem details for `Accept: application/json`, Markdown for `Accept: text/markdown`, HTML otherwise.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/sitemap-index.xml": {
      "get": {
        "operationId": "getSitemapIndex",
        "tags": [
          "discovery"
        ],
        "summary": "Sitemap index",
        "responses": {
          "200": {
            "description": "Sitemap index XML",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Not found. Problem details for `Accept: application/json`, Markdown for `Accept: text/markdown`, HTML otherwise.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RateLimit": {
        "description": "Current quota state (IETF HTTPAPI RateLimit header fields): `r` requests remaining, `t` seconds until the window resets. Example: `\"default\";r=59;t=42`.",
        "schema": {
          "type": "string"
        }
      },
      "RateLimitPolicy": {
        "description": "Quota policy: `q` requests per `w` seconds. Example: `\"default\";q=60;w=60`.",
        "schema": {
          "type": "string"
        }
      },
      "Allow": {
        "description": "Methods the resource supports (RFC 9110 §10.2.1).",
        "schema": {
          "type": "string",
          "example": "GET, HEAD"
        }
      },
      "RetryAfter": {
        "description": "Seconds to wait before retrying (RFC 9110 §10.2.3).",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      },
      "ContentLocation": {
        "description": "The versioned path this alias resolved to.",
        "schema": {
          "type": "string",
          "format": "uri-reference",
          "example": "/api/v1"
        }
      },
      "Deprecation": {
        "description": "RFC 9745. Sent only once this version is deprecated: when deprecation was announced, as `@<unix-seconds>`.",
        "schema": {
          "type": "string",
          "example": "@1798761600"
        }
      },
      "Sunset": {
        "description": "RFC 8594. Sent only once this version is deprecated: the HTTP-date after which it may stop responding.",
        "schema": {
          "type": "string",
          "example": "Thu, 01 Jul 2027 00:00:00 GMT"
        }
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details with extension members.",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "instance",
          "code",
          "hint",
          "docs"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri-reference",
            "example": "about:blank"
          },
          "title": {
            "type": "string",
            "example": "Not Found"
          },
          "status": {
            "type": "integer",
            "example": 404
          },
          "detail": {
            "type": "string",
            "example": "Not Found: /api/unknown"
          },
          "instance": {
            "type": "string",
            "format": "uri-reference",
            "example": "/api/unknown"
          },
          "code": {
            "type": "string",
            "description": "Stable, machine-readable error code. Branch on this, not on `title` or `detail`.",
            "enum": [
              "bad_request",
              "unauthorized",
              "forbidden",
              "not_found",
              "method_not_allowed",
              "not_acceptable",
              "rate_limited",
              "internal_error",
              "service_unavailable",
              "client_error",
              "server_error"
            ],
            "example": "not_found"
          },
          "hint": {
            "type": "string",
            "description": "How to resolve the error."
          },
          "docs": {
            "type": "string",
            "format": "uri",
            "description": "Where the valid endpoints are documented."
          }
        }
      },
      "ApiIndex": {
        "type": "object",
        "required": [
          "name",
          "description",
          "version",
          "resources"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "version": {
            "type": "string",
            "description": "API version that served this response.",
            "example": "v1"
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          },
          "resources": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "title",
                "href",
                "description"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "href": {
                  "type": "string",
                  "format": "uri"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Linkset": {
        "type": "object",
        "required": [
          "linkset"
        ],
        "properties": {
          "linkset": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      }
    }
  }
}