{
  "openapi": "3.1.0",
  "info": {
    "title": "Cosmo by Humanizing — Public Content API",
    "version": "2026-08-23",
    "summary": "Read-only JSON access to the Cosmo product catalogue, pricing and company details.",
    "description": "Read-only API published by Cosmo by Humanizing (Humanizing Technologies GmbH).\n\nIt exposes the same product, pricing and company facts as the marketing site, so agents\ndo not have to scrape HTML. No authentication is required and no rate limit is enforced;\nresponses are cached at the edge for five minutes.\n\nEvery non-2xx response uses the Error schema. The same content is also available as Markdown:\nrequest any page with 'Accept: text/markdown', or append '.md' to its path.",
    "contact": {
      "name": "Humanizing Technologies GmbH — Cosmo",
      "email": "contact@humanizing.com",
      "url": "https://cosmo.humanizing.com/developers"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://cosmo.humanizing.com/terms"
    },
    "termsOfService": "https://cosmo.humanizing.com/terms"
  },
  "servers": [
    {
      "url": "https://cosmo.humanizing.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer resources",
    "url": "https://cosmo.humanizing.com/developers"
  },
  "tags": [
    {
      "name": "Meta",
      "description": "Service metadata and health."
    },
    {
      "name": "Catalog",
      "description": "Cosmo products and the industries they serve."
    },
    {
      "name": "Pricing",
      "description": "Published plans, credits and add-ons."
    },
    {
      "name": "Company",
      "description": "Registered company and contact details."
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Check API availability",
        "description": "Returns the service name, the API version and the current server time. Use it to confirm the API is reachable before issuing other calls.",
        "tags": [
          "Meta"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "The API is available.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "service",
                    "api_version",
                    "time"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "Always 'ok' when the API responds.",
                      "enum": [
                        "ok"
                      ]
                    },
                    "service": {
                      "type": "string",
                      "description": "Service identifier."
                    },
                    "api_version": {
                      "type": "string",
                      "description": "Dated version of the API contract."
                    },
                    "time": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Server time in UTC."
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "The endpoint was called with a method other than GET or HEAD.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/products": {
      "get": {
        "operationId": "listProducts",
        "summary": "List Cosmo products",
        "description": "Lists every Cosmo product with its category, the channels it runs on and a link to its product page. Filter by category to narrow the result.",
        "tags": [
          "Catalog"
        ],
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Return only products in this family.",
            "schema": {
              "type": "string",
              "enum": [
                "chatbot",
                "voicebot",
                "receptionist"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The matching products.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "api_version",
                    "count",
                    "data"
                  ],
                  "properties": {
                    "api_version": {
                      "type": "string",
                      "description": "Dated version of the API contract."
                    },
                    "count": {
                      "type": "integer",
                      "description": "Number of products returned."
                    },
                    "data": {
                      "type": "array",
                      "description": "The products.",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The category parameter was not one of the allowed values.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "The endpoint was called with a method other than GET or HEAD.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/products/{productId}": {
      "get": {
        "operationId": "getProduct",
        "summary": "Get one Cosmo product",
        "description": "Returns a single product by its stable id. Ids are returned by listProducts and do not change.",
        "tags": [
          "Catalog"
        ],
        "parameters": [
          {
            "name": "productId",
            "in": "path",
            "required": true,
            "description": "Stable product identifier.",
            "schema": {
              "type": "string",
              "enum": [
                "chatbot",
                "voicebot",
                "reception-kiosk"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The requested product.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "api_version",
                    "data"
                  ],
                  "properties": {
                    "api_version": {
                      "type": "string",
                      "description": "Dated version of the API contract."
                    },
                    "data": {
                      "$ref": "#/components/schemas/Product"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No product exists with the requested id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "The endpoint was called with a method other than GET or HEAD.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pricing": {
      "get": {
        "operationId": "listPricingPlans",
        "summary": "List plans and add-ons",
        "description": "Returns every published Cosmo plan with list prices, included credits and headline features, plus the add-ons that can be combined with any plan. Prices are in EUR and exclude VAT.",
        "tags": [
          "Pricing"
        ],
        "parameters": [
          {
            "name": "interval",
            "in": "query",
            "required": false,
            "description": "Return only the price for this billing interval. Omit to receive both.",
            "schema": {
              "type": "string",
              "enum": [
                "monthly",
                "yearly"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The published plans and add-ons.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "api_version",
                    "currency",
                    "plans",
                    "add_ons"
                  ],
                  "properties": {
                    "api_version": {
                      "type": "string",
                      "description": "Dated version of the API contract."
                    },
                    "currency": {
                      "type": "string",
                      "description": "ISO 4217 currency for all prices."
                    },
                    "billing_intervals": {
                      "type": "array",
                      "description": "Billing intervals the plans can be bought on.",
                      "items": {
                        "type": "string",
                        "enum": [
                          "monthly",
                          "yearly"
                        ]
                      }
                    },
                    "pricing_page": {
                      "type": "string",
                      "format": "uri",
                      "description": "Human-readable pricing page."
                    },
                    "plans": {
                      "type": "array",
                      "description": "The published plans.",
                      "items": {
                        "$ref": "#/components/schemas/PricingPlan"
                      }
                    },
                    "add_ons": {
                      "type": "array",
                      "description": "Add-ons available on top of a plan.",
                      "items": {
                        "$ref": "#/components/schemas/PricingAddOn"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The interval parameter was not 'monthly' or 'yearly'.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "The endpoint was called with a method other than GET or HEAD.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/company": {
      "get": {
        "operationId": "getCompanyProfile",
        "summary": "Get company and contact details",
        "description": "Returns the registered company behind Cosmo: legal name, postal address, VAT id, commercial register entry, contact email and phone, official social profiles and the industries Cosmo publishes solution pages for.",
        "tags": [
          "Company"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "The company profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "api_version",
                    "data"
                  ],
                  "properties": {
                    "api_version": {
                      "type": "string",
                      "description": "Dated version of the API contract."
                    },
                    "data": {
                      "$ref": "#/components/schemas/Company"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "The endpoint was called with a method other than GET or HEAD.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Envelope returned for every non-2xx response. Branch on error.code, show error.message, act on error.resolution.",
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "object",
            "description": "The failure that occurred.",
            "required": [
              "code",
              "status",
              "message",
              "resolution",
              "documentation_url"
            ],
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code.",
                "enum": [
                  "invalid_request",
                  "unauthorized",
                  "not_found",
                  "method_not_allowed",
                  "not_acceptable",
                  "unsupported_media_type",
                  "rate_limited",
                  "internal_error"
                ]
              },
              "status": {
                "type": "integer",
                "description": "HTTP status code repeated in the body.",
                "examples": [
                  404
                ]
              },
              "message": {
                "type": "string",
                "description": "Human-readable description of what went wrong."
              },
              "resolution": {
                "type": "string",
                "description": "Concrete next step that resolves the error."
              },
              "documentation_url": {
                "type": "string",
                "format": "uri",
                "description": "Page documenting this endpoint and error format."
              }
            }
          }
        }
      },
      "Product": {
        "type": "object",
        "description": "A Cosmo product available to customers.",
        "required": [
          "id",
          "name",
          "category",
          "summary",
          "channels",
          "url"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable product identifier.",
            "examples": [
              "chatbot"
            ]
          },
          "name": {
            "type": "string",
            "description": "Product name as used on the website."
          },
          "category": {
            "type": "string",
            "description": "Product family.",
            "enum": [
              "chatbot",
              "voicebot",
              "receptionist"
            ]
          },
          "summary": {
            "type": "string",
            "description": "One-sentence description of what the product does."
          },
          "channels": {
            "type": "array",
            "description": "Channels the product operates on.",
            "items": {
              "type": "string"
            }
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical product page."
          }
        }
      },
      "PricingPlan": {
        "type": "object",
        "description": "A published Cosmo subscription plan.",
        "required": [
          "id",
          "name",
          "description",
          "currency",
          "contact_sales",
          "features"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable plan identifier.",
            "examples": [
              "standard"
            ]
          },
          "name": {
            "type": "string",
            "description": "Plan name shown on the pricing page."
          },
          "description": {
            "type": "string",
            "description": "Who the plan is for."
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency code.",
            "examples": [
              "EUR"
            ]
          },
          "monthly_price": {
            "type": [
              "number",
              "null"
            ],
            "description": "Monthly list price, or null when the plan is quoted by sales."
          },
          "yearly_price": {
            "type": [
              "number",
              "null"
            ],
            "description": "Yearly list price, or null when the plan is quoted by sales."
          },
          "contact_sales": {
            "type": "boolean",
            "description": "True when the plan has no list price and requires a sales conversation."
          },
          "included_credits_per_month": {
            "type": [
              "integer",
              "string"
            ],
            "description": "Credits included per month, or a descriptive value for custom plans."
          },
          "included_agents": {
            "type": [
              "integer",
              "string"
            ],
            "description": "Agents included, or a descriptive value for custom plans."
          },
          "features": {
            "type": "array",
            "description": "Headline features included in the plan.",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "PricingAddOn": {
        "type": "object",
        "description": "A paid add-on that can be combined with any plan.",
        "required": [
          "id",
          "name",
          "description",
          "amount",
          "unit",
          "period"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable add-on identifier."
          },
          "name": {
            "type": "string",
            "description": "Add-on name."
          },
          "description": {
            "type": "string",
            "description": "What the add-on provides."
          },
          "amount": {
            "type": "number",
            "description": "Price in the plan currency."
          },
          "unit": {
            "type": "string",
            "description": "What the price is charged per."
          },
          "period": {
            "type": "string",
            "description": "Billing period the price applies to."
          }
        }
      },
      "Company": {
        "type": "object",
        "description": "Registered details of the company behind Cosmo.",
        "required": [
          "legal_name",
          "product_name",
          "url",
          "email",
          "telephone",
          "address"
        ],
        "properties": {
          "legal_name": {
            "type": "string",
            "description": "Registered company name."
          },
          "product_name": {
            "type": "string",
            "description": "Product brand name."
          },
          "description": {
            "type": "string",
            "description": "What the company builds."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Product website."
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "General contact address."
          },
          "telephone": {
            "type": "string",
            "description": "Contact phone number in E.164 format."
          },
          "address": {
            "type": "object",
            "description": "Registered postal address.",
            "required": [
              "street_address",
              "postal_code",
              "locality",
              "country",
              "country_code"
            ],
            "properties": {
              "street_address": {
                "type": "string",
                "description": "Street and house number."
              },
              "postal_code": {
                "type": "string",
                "description": "Postal code."
              },
              "locality": {
                "type": "string",
                "description": "City."
              },
              "country": {
                "type": "string",
                "description": "Country name."
              },
              "country_code": {
                "type": "string",
                "description": "ISO 3166-1 alpha-2 country code."
              }
            }
          },
          "vat_id": {
            "type": "string",
            "description": "EU VAT identification number."
          },
          "registration": {
            "type": "object",
            "description": "Commercial register entry.",
            "properties": {
              "court": {
                "type": "string",
                "description": "Registering court."
              },
              "number": {
                "type": "string",
                "description": "Commercial register number."
              }
            }
          },
          "founders_or_directors": {
            "type": "array",
            "description": "Managing directors named in the Impressum.",
            "items": {
              "type": "string"
            }
          },
          "social_profiles": {
            "type": "array",
            "description": "Official company profiles on third-party platforms.",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "industries": {
            "type": "array",
            "description": "Industries Cosmo publishes solution pages for.",
            "items": {
              "type": "object",
              "required": [
                "id",
                "name",
                "url"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Industry slug."
                },
                "name": {
                  "type": "string",
                  "description": "Industry name."
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Industry page."
                }
              }
            }
          }
        }
      }
    }
  }
}