{
  "openapi": "3.1.0",
  "info": {
    "title": "Cost-Effective Software Public API",
    "version": "1.1.0",
    "summary": "Public API of Cost-Effective Software (costeffective.software).",
    "description": "Public, unauthenticated endpoints of Cost-Effective Software — custom software and AI automation for businesses.\n\n## Versioning & deprecation policy\nThe canonical REST surface is versioned in the URL path: `/api/v1/...`. The unversioned\n`/api/health` and `/api/contact` paths are stable aliases of their v1 equivalents.\nBreaking changes only ship in a new path version (`/api/v2/...`); a version being retired is\nannounced at least 6 months in advance via `Deprecation` and `Sunset` response headers on the\naffected endpoints and a notice in this document and at /developers.\n\n## Rate limits\nPublic API endpoints are limited to 60 requests per 60-second window per client IP.\nEvery response carries IETF `RateLimit-*` headers; a `429` response includes `Retry-After`.\n\n## Authentication\nNone required for any endpoint in this document (zero-auth). Protected internal APIs are\ndocumented separately at /auth.md.\n\nBeyond this REST surface:\n- A read-only MCP server (Streamable HTTP) at https://www.costeffective.software/mcp — manifest at https://www.costeffective.software/.well-known/mcp.json\n- Markdown mirrors of every public page at https://www.costeffective.software/md/{path}; pages also honour `Accept: text/markdown`\n- Agent instructions (when to use us) at https://www.costeffective.software/agents.md\n- Agent authentication guide at https://www.costeffective.software/auth.md\n- Site guide for AI agents at https://www.costeffective.software/llms.txt",
    "contact": {
      "name": "Cost-Effective Software",
      "url": "https://www.costeffective.software/developers",
      "email": "team@costeffective.software"
    }
  },
  "servers": [
    {
      "url": "https://www.costeffective.software",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer resources",
    "url": "https://www.costeffective.software/developers"
  },
  "tags": [
    {
      "name": "status",
      "description": "Service status endpoints"
    },
    {
      "name": "leads",
      "description": "Consultation / contact requests"
    },
    {
      "name": "content",
      "description": "Machine-readable site content for agents"
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "operationId": "healthCheck",
        "tags": [
          "status"
        ],
        "summary": "Service health check",
        "description": "Returns the service status. Responds `{\"status\":\"ok\"}` when the API is up. Canonical v1 path.",
        "responses": {
          "200": {
            "description": "Service is up",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/contact": {
      "post": {
        "operationId": "requestConsultation",
        "tags": [
          "leads"
        ],
        "summary": "Submit a consultation / contact request",
        "description": "Sends a lead to the Cost-Effective Software team. Same action as the MCP tool `request_consultation`. Canonical v1 path.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid fields — `name`, `email` and `message` are required, `email` must be a valid address",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Lead delivery failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "healthCheckUnversioned",
        "tags": [
          "status"
        ],
        "summary": "Service health check (stable alias of /api/v1/health)",
        "description": "Stable unversioned alias of `/api/v1/health`. Identical behavior; prefer the v1 path for new integrations.",
        "responses": {
          "200": {
            "description": "Service is up",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Unexpected server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "operationId": "requestConsultationUnversioned",
        "tags": [
          "leads"
        ],
        "summary": "Submit a consultation request (stable alias of /api/v1/contact)",
        "description": "Stable unversioned alias of `/api/v1/contact`. Identical behavior; prefer the v1 path for new integrations.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid fields — `name`, `email` and `message` are required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "description": "Lead delivery failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/md/{path}": {
      "get": {
        "operationId": "getMarkdownMirror",
        "tags": [
          "content"
        ],
        "summary": "Markdown mirror of a public page",
        "description": "Token-efficient markdown rendition of any public page, e.g. `/md/careers` or `/md` for the homepage. The parameter may contain `/` separators.",
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "required": true,
            "description": "Page path to mirror, without the leading slash (e.g. `careers`, `industries/logistics`). Use `/md` alone for the homepage.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_/-]+$",
              "examples": [
                "careers"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown rendition of the page",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          },
          "404": {
            "description": "No such public page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Markdown conversion failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiSpec",
        "tags": [
          "content"
        ],
        "summary": "This OpenAPI document",
        "description": "The machine-readable OpenAPI 3.1 description of this API, served as JSON.",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 specification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenApiDocument"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "tags": [
          "content"
        ],
        "summary": "llms.txt site guide for AI agents",
        "description": "Plain-text llms.txt document: what this site offers, when agents should use it, and links to every machine-readable resource.",
        "responses": {
          "200": {
            "description": "llms.txt document",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RateLimitLimit": {
        "description": "Requests allowed in the current window (IETF RateLimit fields)",
        "schema": {
          "type": "integer",
          "examples": [
            60
          ]
        }
      },
      "RateLimitRemaining": {
        "description": "Requests remaining in the current window",
        "schema": {
          "type": "integer",
          "examples": [
            59
          ]
        }
      },
      "RateLimitReset": {
        "description": "Seconds until the current window resets",
        "schema": {
          "type": "integer",
          "examples": [
            42
          ]
        }
      },
      "RetryAfter": {
        "description": "Seconds to wait before retrying (sent with 429 responses)",
        "schema": {
          "type": "integer",
          "examples": [
            42
          ]
        }
      }
    },
    "responses": {
      "RateLimited": {
        "description": "Rate limit exceeded — retry after the number of seconds in `Retry-After`",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitLimit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitRemaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "Health": {
        "type": "object",
        "description": "Service health status",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ],
            "description": "Always \"ok\" when the service is up"
          }
        },
        "required": [
          "status"
        ]
      },
      "ContactRequest": {
        "type": "object",
        "description": "A consultation / contact request",
        "properties": {
          "name": {
            "type": "string",
            "description": "Full name of the requester"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Reply-to email address"
          },
          "company": {
            "type": "string",
            "description": "Company name (optional)"
          },
          "message": {
            "type": "string",
            "description": "What you want to build or automate"
          }
        },
        "required": [
          "name",
          "email",
          "message"
        ]
      },
      "ContactResponse": {
        "type": "object",
        "description": "Acknowledgement that the request was delivered",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "True when the lead was delivered to the team"
          }
        },
        "required": [
          "success"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Typed error envelope returned by every 4xx/5xx JSON response",
        "properties": {
          "error": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Always true on error responses"
          },
          "statusCode": {
            "type": "integer",
            "description": "HTTP status code, machine-readable"
          },
          "statusMessage": {
            "type": "string",
            "description": "Short machine-readable error summary"
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation of the failure"
          },
          "url": {
            "type": "string",
            "description": "The request path that failed"
          },
          "data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Optional structured error details"
          }
        },
        "required": [
          "statusCode",
          "message"
        ]
      },
      "MarkdownDocument": {
        "type": "string",
        "description": "A UTF-8 markdown (or plain text) document"
      },
      "OpenApiDocument": {
        "type": "object",
        "description": "An OpenAPI 3.1 document",
        "properties": {
          "openapi": {
            "type": "string",
            "description": "OpenAPI version, e.g. 3.1.0"
          },
          "info": {
            "type": "object",
            "additionalProperties": true
          },
          "paths": {
            "type": "object",
            "additionalProperties": true
          },
          "components": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "openapi",
          "info",
          "paths"
        ]
      }
    }
  }
}