{
  "openapi": "3.1.0",
  "info": {
    "title": "Raum Network Agent API",
    "version": "1.0.0",
    "description": "Read-only, public catalog for agents and developers discovering Raum Network capabilities, projects, and machine-readable resources. API uses URL versioning under /api/v1. Version 1 is active; deprecation and sunset signals are documented at https://www.raum.network/api/versioning. Named developer resources, including the MCP server and CLI, are indexed at https://www.raum.network/developers.",
    "contact": {
      "name": "Raum Network",
      "email": "comms@raum.network",
      "url": "https://www.raum.network/contact"
    }
  },
  "servers": [
    {
      "url": "https://www.raum.network",
      "description": "Raum Network production API"
    }
  ],
  "tags": [
    {
      "name": "catalog",
      "description": "Discover Raum Network company, services, projects, and agent resources."
    }
  ],
  "externalDocs": {
    "description": "Raum Network named developer resources and agent integration guidance",
    "url": "https://www.raum.network/developers"
  },
  "paths": {
    "/api/v1/catalog": {
      "get": {
        "tags": ["catalog"],
        "operationId": "getCatalog",
        "summary": "Get agent discovery catalog",
        "description": "Returns typed company, service, project, and machine-readable resource metadata. Use this endpoint before selecting a service or project-specific page. Optional limit bounds response collection sizes from 1 through 50.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of services and projects to return.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog returned successfully.",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "Link": { "$ref": "#/components/headers/DeprecationPolicyLink" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          },
          "405": {
            "description": "HTTP method is not supported.",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "Link": { "$ref": "#/components/headers/DeprecationPolicyLink" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "400": {
            "description": "Query parameter is invalid.",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "Link": { "$ref": "#/components/headers/DeprecationPolicyLink" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Client exceeded the per-window request quota.",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" },
              "Retry-After": { "$ref": "#/components/headers/RetryAfter" },
              "API-Version": { "$ref": "#/components/headers/ApiVersion" },
              "Link": { "$ref": "#/components/headers/DeprecationPolicyLink" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RateLimitLimit": {
        "description": "Maximum requests permitted in the current client window.",
        "schema": { "type": "integer", "minimum": 1 }
      },
      "RateLimitRemaining": {
        "description": "Requests remaining in the current client window.",
        "schema": { "type": "integer", "minimum": 0 }
      },
      "RateLimitReset": {
        "description": "Seconds until the current client window resets.",
        "schema": { "type": "integer", "minimum": 1 }
      },
      "RateLimitPolicy": {
        "description": "Quota policy expressed as 60 requests in a 60-second window.",
        "schema": { "type": "string", "example": "60;w=60" }
      },
      "RetryAfter": {
        "description": "Seconds to wait before retrying after a 429 response.",
        "schema": { "type": "integer", "minimum": 1 }
      },
      "ApiVersion": {
        "description": "Active URL API contract version.",
        "schema": { "type": "string", "example": "1.0.0" }
      },
      "DeprecationPolicyLink": {
        "description": "Link to current API deprecation policy; active versions omit Deprecation and Sunset until a dated retirement is announced.",
        "schema": { "type": "string", "example": "<https://www.raum.network/api/versioning>; rel=\"deprecation\"; type=\"text/html\"" }
      }
    },
    "schemas": {
      "Company": {
        "type": "object",
        "required": ["name", "legalName", "description", "location", "email", "website", "documentation"],
        "properties": {
          "name": { "type": "string", "description": "Public company name." },
          "legalName": { "type": "string", "description": "Legal entity name." },
          "description": { "type": "string", "description": "Company capability summary." },
          "location": { "type": "string", "description": "Primary company location." },
          "email": { "type": "string", "format": "email", "description": "Public contact email." },
          "website": { "type": "string", "format": "uri", "description": "Canonical website URL." },
          "documentation": { "type": "string", "format": "uri", "description": "Technical documentation URL." }
        },
        "additionalProperties": false
      },
      "Service": {
        "type": "object",
        "required": ["id", "name", "description", "url"],
        "properties": {
          "id": { "type": "string", "description": "Stable service identifier." },
          "name": { "type": "string", "description": "Service name." },
          "description": { "type": "string", "description": "Service capability summary." },
          "url": { "type": "string", "format": "uri", "description": "Canonical service page." }
        },
        "additionalProperties": false
      },
      "Project": {
        "type": "object",
        "required": ["id", "name", "description", "url", "productUrl"],
        "properties": {
          "id": { "type": "string", "description": "Stable project identifier." },
          "name": { "type": "string", "description": "Project name." },
          "description": { "type": "string", "description": "Project capability summary." },
          "url": { "type": "string", "format": "uri", "description": "Canonical project page." },
          "productUrl": { "type": "string", "format": "uri", "description": "Live product URL." }
        },
        "additionalProperties": false
      },
      "Links": {
        "type": "object",
        "required": ["developers", "api", "llms", "llmsFull", "openapi", "mcp", "mcpManifest", "cli", "pricing", "sitemap", "contact"],
        "properties": {
          "developers": { "type": "string", "format": "uri" },
          "api": { "type": "string", "format": "uri" },
          "llms": { "type": "string", "format": "uri" },
          "llmsFull": { "type": "string", "format": "uri" },
          "openapi": { "type": "string", "format": "uri" },
          "mcp": { "type": "string", "format": "uri" },
          "mcpManifest": { "type": "string", "format": "uri" },
          "cli": { "type": "string", "format": "uri" },
          "pricing": { "type": "string", "format": "uri" },
          "sitemap": { "type": "string", "format": "uri" },
          "contact": { "type": "string", "format": "uri" }
        },
        "additionalProperties": false
      },
      "Catalog": {
        "type": "object",
        "required": ["apiVersion", "company", "services", "projects", "links"],
        "properties": {
          "apiVersion": { "type": "string", "description": "Catalog contract version." },
          "company": { "$ref": "#/components/schemas/Company" },
          "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } },
          "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } },
          "links": { "$ref": "#/components/schemas/Links" }
        },
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "required": ["code", "message", "resolution"],
        "properties": {
          "code": { "type": "string", "description": "Stable machine-readable error code." },
          "message": { "type": "string", "description": "Human-readable error message." },
          "resolution": { "type": "string", "description": "Action an agent can take to recover." }
        },
        "additionalProperties": false
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "$ref": "#/components/schemas/Error" }
        },
        "additionalProperties": false
      }
    }
  }
}