{
  "openapi": "3.1.0",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "SumWise Compute REST API",
    "version": "v1-private-alpha-draft",
    "description": "Authoritative machine-readable presentation of the current private-alpha Draft REST contract. This document does not promise general availability, a production SLA, or public access without an authorized opaque bearer API key. The normative expression grammar, exactness rules, limits guidance, privacy boundary, and integration examples are in docs/compute/REST_INTEGRATION_GUIDE.md. SumWise implementation source remains private and proprietary."
  },
  "servers": [
    {
      "url": "https://api.sumwisecalc.com",
      "description": "SumWise-hosted Compute over HTTPS"
    }
  ],
  "security": [
    {
      "opaqueBearerApiKey": []
    }
  ],
  "paths": {
    "/v1/evaluate": {
      "post": {
        "operationId": "evaluate",
        "summary": "Evaluate one deterministic mathematical expression",
        "description": "Accepts exactly one expression string. The query string must be empty. The complete serialized UTF-8 JSON body is limited to 4096 bytes inclusive; this is a body-byte limit and is intentionally not represented as JSON Schema maxLength. The aggregation functions sum, mean, min, and max accept 1 through 30 arguments. The scalar utilities abs, sign, floor, ceil, and trunc accept exactly one argument. The REST Integration Guide is the normative grammar explanation. Rate and quota quantities are credential-specific and communicated separately. Some private fail-stop outcomes intentionally produce no application response.",
        "requestBody": {
          "required": true,
          "description": "One complete UTF-8 application/json body with an exact Content-Length. Transfer encoding is not accepted.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EvaluateRequest"
              },
              "examples": {
                "exactRational": {
                  "$ref": "#/components/examples/ExactRationalRequest"
                },
                "aggregation": {
                  "$ref": "#/components/examples/AggregationRequest"
                }
              }
            }
          }
        },
        "responses": {
          "200": {"$ref": "#/components/responses/EvaluateSuccess"},
          "400": {"$ref": "#/components/responses/BadRequest"},
          "401": {"$ref": "#/components/responses/AuthenticationRequired"},
          "404": {"$ref": "#/components/responses/RouteNotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "411": {"$ref": "#/components/responses/ContentLengthRequired"},
          "413": {"$ref": "#/components/responses/RequestBodyTooLarge"},
          "415": {"$ref": "#/components/responses/UnsupportedMediaType"},
          "422": {"$ref": "#/components/responses/ComputeRejected"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "500": {"$ref": "#/components/responses/InternalError"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"},
          "504": {"$ref": "#/components/responses/ComputationTimeout"}
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "opaqueBearerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Opaque issued SumWise Compute API key. Its token syntax is not a public contract. Send it only in the Authorization header and keep it out of URLs, bodies, logs, and browser-delivered code."
      }
    },
    "schemas": {
      "EvaluateRequest": {"$ref": "../schema/sumwise-compute-v1.schema.json#/$defs/EvaluateRequest"},
      "SuccessResponse": {"$ref": "../schema/sumwise-compute-v1.schema.json#/$defs/SuccessResponse"},
      "BadRequestProblem": {"$ref": "../schema/sumwise-compute-v1.schema.json#/$defs/BadRequestProblem"},
      "AuthenticationProblem": {"$ref": "../schema/sumwise-compute-v1.schema.json#/$defs/AuthenticationProblem"},
      "NotFoundProblem": {"$ref": "../schema/sumwise-compute-v1.schema.json#/$defs/NotFoundProblem"},
      "MethodNotAllowedProblem": {"$ref": "../schema/sumwise-compute-v1.schema.json#/$defs/MethodNotAllowedProblem"},
      "LengthRequiredProblem": {"$ref": "../schema/sumwise-compute-v1.schema.json#/$defs/LengthRequiredProblem"},
      "PayloadTooLargeProblem": {"$ref": "../schema/sumwise-compute-v1.schema.json#/$defs/PayloadTooLargeProblem"},
      "UnsupportedMediaTypeProblem": {"$ref": "../schema/sumwise-compute-v1.schema.json#/$defs/UnsupportedMediaTypeProblem"},
      "UnprocessableEntityProblem": {"$ref": "../schema/sumwise-compute-v1.schema.json#/$defs/UnprocessableEntityProblem"},
      "TooManyRequestsProblem": {"$ref": "../schema/sumwise-compute-v1.schema.json#/$defs/TooManyRequestsProblem"},
      "InternalErrorProblem": {"$ref": "../schema/sumwise-compute-v1.schema.json#/$defs/InternalErrorProblem"},
      "ServiceUnavailableProblem": {"$ref": "../schema/sumwise-compute-v1.schema.json#/$defs/ServiceUnavailableProblem"},
      "GatewayTimeoutProblem": {"$ref": "../schema/sumwise-compute-v1.schema.json#/$defs/GatewayTimeoutProblem"}
    },
    "headers": {
      "RequestId": {
        "description": "Opaque request identifier for support and reconciliation. Its syntax is not externally frozen.",
        "schema": {"type": "string"}
      },
      "NoStore": {
        "description": "Prevents caching of the application response.",
        "schema": {"type": "string", "const": "no-store"}
      },
      "NoSniff": {
        "description": "Disables content-type sniffing.",
        "schema": {"type": "string", "const": "nosniff"}
      },
      "RetryAfterDeltaSeconds": {
        "description": "Positive decimal delta-seconds to the known rate or quota reset. HTTP-date form is not supported.",
        "schema": {"type": "string", "pattern": "^[1-9][0-9]*$"}
      },
      "AllowPost": {
        "description": "The only accepted method for this route.",
        "schema": {"type": "string", "const": "POST"}
      },
      "BearerChallenge": {
        "description": "Uniform bearer authentication challenge.",
        "schema": {"type": "string", "const": "Bearer realm=\"SumWise Compute\""}
      }
    },
    "examples": {
      "ExactRationalRequest": {
        "summary": "Exact rational arithmetic",
        "value": {"expression": "1/3 + 5/6"}
      },
      "AggregationRequest": {
        "summary": "Scalar aggregation",
        "value": {"expression": "sum(12,18,25)"}
      },
      "ExactRationalSuccess": {
        "summary": "Exact rational result",
        "value": {
          "ok": true,
          "api_version": "v1",
          "operation": "evaluate",
          "engine_version": "0.1.0-dev.1+untrusted.local",
          "result": {
            "type": "rational",
            "text": "7/6",
            "exactness": "exact",
            "value": {"numerator": "7", "denominator": "6"}
          }
        }
      },
      "AggregationSuccess": {
        "summary": "Exact integer aggregation result",
        "value": {
          "ok": true,
          "api_version": "v1",
          "operation": "evaluate",
          "engine_version": "0.1.0-dev.1+untrusted.local",
          "result": {
            "type": "integer",
            "text": "55",
            "exactness": "exact",
            "value": "55"
          }
        }
      },
      "AuthenticationProblem": {
        "summary": "Uniform authentication failure",
        "value": {
          "type": "https://sumwisecalc.com/compute/service/problems/v1/authentication-required",
          "title": "Authentication required",
          "status": 401,
          "detail": "A valid private-alpha API key is required.",
          "code": "authentication_required"
        }
      }
    },
    "responses": {
      "EvaluateSuccess": {
        "description": "A closed integer, rational, or finite approximate-real success body. Content-Type is application/json.",
        "headers": {
          "X-Request-Id": {"$ref": "#/components/headers/RequestId"},
          "Cache-Control": {"$ref": "#/components/headers/NoStore"},
          "X-Content-Type-Options": {"$ref": "#/components/headers/NoSniff"}
        },
        "content": {
          "application/json": {
            "schema": {"$ref": "#/components/schemas/SuccessResponse"},
            "examples": {
              "exactRational": {"$ref": "#/components/examples/ExactRationalSuccess"},
              "aggregation": {"$ref": "#/components/examples/AggregationSuccess"}
            }
          }
        }
      },
      "BadRequest": {
        "description": "Invalid HTTP framing. Content-Type is application/problem+json.",
        "headers": {
          "X-Request-Id": {"$ref": "#/components/headers/RequestId"},
          "Cache-Control": {"$ref": "#/components/headers/NoStore"},
          "X-Content-Type-Options": {"$ref": "#/components/headers/NoSniff"}
        },
        "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/BadRequestProblem"}}}
      },
      "AuthenticationRequired": {
        "description": "Uniform authentication failure. Content-Type is application/problem+json.",
        "headers": {
          "X-Request-Id": {"$ref": "#/components/headers/RequestId"},
          "Cache-Control": {"$ref": "#/components/headers/NoStore"},
          "X-Content-Type-Options": {"$ref": "#/components/headers/NoSniff"},
          "WWW-Authenticate": {"$ref": "#/components/headers/BearerChallenge"}
        },
        "content": {
          "application/problem+json": {
            "schema": {"$ref": "#/components/schemas/AuthenticationProblem"},
            "examples": {"authenticationRequired": {"$ref": "#/components/examples/AuthenticationProblem"}}
          }
        }
      },
      "RouteNotFound": {
        "description": "The exact route was not found. Content-Type is application/problem+json.",
        "headers": {
          "X-Request-Id": {"$ref": "#/components/headers/RequestId"},
          "Cache-Control": {"$ref": "#/components/headers/NoStore"},
          "X-Content-Type-Options": {"$ref": "#/components/headers/NoSniff"}
        },
        "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/NotFoundProblem"}}}
      },
      "MethodNotAllowed": {
        "description": "The route accepts POST only. Content-Type is application/problem+json.",
        "headers": {
          "X-Request-Id": {"$ref": "#/components/headers/RequestId"},
          "Cache-Control": {"$ref": "#/components/headers/NoStore"},
          "X-Content-Type-Options": {"$ref": "#/components/headers/NoSniff"},
          "Allow": {"$ref": "#/components/headers/AllowPost"}
        },
        "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/MethodNotAllowedProblem"}}}
      },
      "ContentLengthRequired": {
        "description": "A single valid Content-Length is required. Content-Type is application/problem+json.",
        "headers": {
          "X-Request-Id": {"$ref": "#/components/headers/RequestId"},
          "Cache-Control": {"$ref": "#/components/headers/NoStore"},
          "X-Content-Type-Options": {"$ref": "#/components/headers/NoSniff"}
        },
        "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/LengthRequiredProblem"}}}
      },
      "RequestBodyTooLarge": {
        "description": "The complete serialized UTF-8 request body exceeds 4096 bytes. Content-Type is application/problem+json.",
        "headers": {
          "X-Request-Id": {"$ref": "#/components/headers/RequestId"},
          "Cache-Control": {"$ref": "#/components/headers/NoStore"},
          "X-Content-Type-Options": {"$ref": "#/components/headers/NoSniff"}
        },
        "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/PayloadTooLargeProblem"}}}
      },
      "UnsupportedMediaType": {
        "description": "The request media type or charset is unsupported. Content-Type is application/problem+json.",
        "headers": {
          "X-Request-Id": {"$ref": "#/components/headers/RequestId"},
          "Cache-Control": {"$ref": "#/components/headers/NoStore"},
          "X-Content-Type-Options": {"$ref": "#/components/headers/NoSniff"}
        },
        "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/UnsupportedMediaTypeProblem"}}}
      },
      "ComputeRejected": {
        "description": "The request or expression was rejected by the closed Compute contract. Content-Type is application/problem+json.",
        "headers": {
          "X-Request-Id": {"$ref": "#/components/headers/RequestId"},
          "Cache-Control": {"$ref": "#/components/headers/NoStore"},
          "X-Content-Type-Options": {"$ref": "#/components/headers/NoSniff"}
        },
        "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/UnprocessableEntityProblem"}}}
      },
      "TooManyRequests": {
        "description": "Per-key concurrency, accepted-request rate, or Compute quota rejection. Retry-After is present and required only for rate_limit_exceeded and quota_exhausted; it is not defined for concurrent_request_limit_exceeded. Content-Type is application/problem+json.",
        "headers": {
          "X-Request-Id": {"$ref": "#/components/headers/RequestId"},
          "Cache-Control": {"$ref": "#/components/headers/NoStore"},
          "X-Content-Type-Options": {"$ref": "#/components/headers/NoSniff"},
          "Retry-After": {"$ref": "#/components/headers/RetryAfterDeltaSeconds"}
        },
        "x-sumwise-header-conditions": {
          "Retry-After": {
            "requiredForProblemCodes": ["rate_limit_exceeded", "quota_exhausted"],
            "absentForProblemCodes": ["concurrent_request_limit_exceeded"]
          }
        },
        "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/TooManyRequestsProblem"}}}
      },
      "InternalError": {
        "description": "The service could not safely produce a result. Content-Type is application/problem+json.",
        "headers": {
          "X-Request-Id": {"$ref": "#/components/headers/RequestId"},
          "Cache-Control": {"$ref": "#/components/headers/NoStore"},
          "X-Content-Type-Options": {"$ref": "#/components/headers/NoSniff"}
        },
        "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/InternalErrorProblem"}}}
      },
      "ServiceUnavailable": {
        "description": "A deliverable service busy or unavailable response. Some private fail-stop outcomes submit no application response instead. Content-Type is application/problem+json.",
        "headers": {
          "X-Request-Id": {"$ref": "#/components/headers/RequestId"},
          "Cache-Control": {"$ref": "#/components/headers/NoStore"},
          "X-Content-Type-Options": {"$ref": "#/components/headers/NoSniff"}
        },
        "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/ServiceUnavailableProblem"}}}
      },
      "ComputationTimeout": {
        "description": "The computation exceeded the private service time limit. No Retry-After header is defined. Content-Type is application/problem+json.",
        "headers": {
          "X-Request-Id": {"$ref": "#/components/headers/RequestId"},
          "Cache-Control": {"$ref": "#/components/headers/NoStore"},
          "X-Content-Type-Options": {"$ref": "#/components/headers/NoSniff"}
        },
        "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/GatewayTimeoutProblem"}}}
      }
    }
  }
}