{"openapi":"3.1.0","info":{"title":"Aguasto Public Research API","version":"1.0.0","description":"Anonymous read-only research search and educational calculations. GPU capacity is not currently bookable. No public inference API, model endpoint, account, reservation or token pricing is available. Calculations are educational estimates, not quotes or deployment guarantees. Versioning and deprecation policy: v1 accepts additive optional fields; breaking changes use a new major URL version. Before retiring an operation, publish its replacement and removal date at least 90 days ahead. Deprecated operations will emit Deprecation and Sunset headers. No v1 operation is currently deprecated.","contact":{"name":"Aguasto","url":"https://www.aguasto.com/contact","email":"contact@aguasto.com"}},"servers":[{"url":"https://www.aguasto.com"}],"security":[],"externalDocs":{"description":"API versioning and deprecation policy, public access and CLI instructions","url":"https://www.aguasto.com/developers/versioning"},"x-aguasto-integrations":{"repository":"https://github.com/Altssdata/aguasto-agents","npm":"https://www.npmjs.com/package/aguasto-research","go":"https://pkg.go.dev/github.com/Altssdata/aguasto-agents/go","mcp":{"directory":"https://mcp.so/servers/aguasto-research","research":"https://registry.modelcontextprotocol.io/v0.1/servers/com.aguasto.www%2Fdocs/versions/1.0.0","calculators":"https://registry.modelcontextprotocol.io/v0.1/servers/com.aguasto.www%2Ftools/versions/1.0.0"},"skills":{"research":"https://skills.sh/altssdata/aguasto-agents/aguasto-research","calculations":"https://skills.sh/altssdata/aguasto-agents/aguasto-calculations","integrationTesting":"https://skills.sh/altssdata/aguasto-agents/aguasto-integration-testing"}},"components":{"schemas":{"Error":{"type":"object","description":"Stable REST error envelope. Inspect error.code; message explains the rejected request.","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_ARGUMENT","NOT_FOUND","RATE_LIMITED","INVALID_IDEMPOTENCY_KEY","IDEMPOTENCY_MISMATCH"]},"message":{"type":"string"}}}}}}},"paths":{"/api/v1/sandbox":{"get":{"operationId":"describeSandbox","summary":"Inspect the synthetic integration test environment","description":"No credentials or production research data. Returns two fixed synthetic references and allowed test operations. Shares the calculator per-instance admission limit.","responses":{"200":{"description":"Synthetic fixtures and supported operations.","content":{"application/json":{"schema":{"type":"object","required":["environment","synthetic","fixtures","operations"],"properties":{"environment":{"const":"sandbox"},"synthetic":{"const":true},"authentication":{"const":"none"},"documentation":{"type":"string"},"fixtures":{"type":"array","items":{"type":"object","required":["id","name","description"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}}},"operations":{"type":"array","items":{"enum":["search","calculate"]}},"persistence":{"const":"none"}}}}},"headers":{"Link":{"description":"Link to the versioning and retirement policy with rel=deprecation; this does not mark an active operation deprecated.","schema":{"type":"string"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the per-instance window resets.","schema":{"type":"integer"}}}},"400":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-instance request window exhausted. Retry after the indicated delay; this is not a global quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Link":{"description":"Link to the versioning and retirement policy with rel=deprecation; this does not mark an active operation deprecated.","schema":{"type":"string"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the per-instance window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Window reset as Unix seconds.","schema":{"type":"integer"}}}}}},"post":{"operationId":"testSandbox","summary":"Test synthetic search and educational calculations","description":"Exercises bounded request parsing, synthetic search, empty results and pure calculations without reading or modifying production research records. Never creates jobs, accounts, GPU capacity, inference or payments. Shares the calculator per-instance admission limit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["operation","query"],"additionalProperties":false,"properties":{"operation":{"const":"search"},"query":{"type":"string","minLength":1,"maxLength":2000}}},{"type":"object","required":["operation","calculation","parameters"],"additionalProperties":false,"properties":{"operation":{"const":"calculate"},"calculation":{"const":"weight_memory"},"parameters":{"type":"object","properties":{"parameters_billions":{"type":"number","exclusiveMinimum":0},"bits":{"type":"number","enum":[4,8,16,32]}},"required":["parameters_billions","bits"],"additionalProperties":false}}},{"type":"object","required":["operation","calculation","parameters"],"additionalProperties":false,"properties":{"operation":{"const":"calculate"},"calculation":{"const":"facility_energy"},"parameters":{"type":"object","properties":{"it_kw":{"type":"number","minimum":0},"pue":{"type":"number","minimum":1},"hours":{"type":"number","minimum":0},"usd_per_kwh":{"type":"number","minimum":0}},"required":["it_kw","pue","hours","usd_per_kwh"],"additionalProperties":false}}},{"type":"object","required":["operation","calculation","parameters"],"additionalProperties":false,"properties":{"operation":{"const":"calculate"},"calculation":{"const":"token_cost"},"parameters":{"type":"object","properties":{"cost_usd":{"type":"number","minimum":0},"completed_tokens":{"type":"number","exclusiveMinimum":0}},"required":["cost_usd","completed_tokens"],"additionalProperties":false}}}]}}}},"responses":{"200":{"description":"Synthetic test response. Search records contain id, name and description; calculations use the documented units and limitations.","content":{"application/json":{"schema":{"type":"object","required":["environment","synthetic","persistence","result","limitations"],"properties":{"environment":{"const":"sandbox"},"synthetic":{"const":true},"persistence":{"const":"none"},"result":{"type":"object"},"limitations":{"type":"string"}}}}},"headers":{"Link":{"description":"Link to the versioning and retirement policy with rel=deprecation; this does not mark an active operation deprecated.","schema":{"type":"string"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the per-instance window resets.","schema":{"type":"integer"}}}},"400":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-instance request window exhausted. Retry after the indicated delay; this is not a global quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Link":{"description":"Link to the versioning and retirement policy with rel=deprecation; this does not mark an active operation deprecated.","schema":{"type":"string"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the per-instance window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Window reset as Unix seconds.","schema":{"type":"integer"}}}}}}},"/api/v1/catalog":{"get":{"operationId":"listPages","summary":"List published page descriptions and canonical links","description":"Optional offset pagination. Omit parameters to retrieve the complete current inventory. Follow pagination.next_offset until null; page content can change between requests.","parameters":[{"name":"limit","in":"query","description":"Maximum pages to return; the default is the complete inventory.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","description":"Zero-based position of the first page.","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}}],"responses":{"200":{"description":"Published page inventory.","content":{"application/json":{"schema":{"type":"object","required":["pages","limitations","pagination"],"properties":{"pages":{"type":"array","items":{"type":"object","required":["name","description","url","dateModified"],"properties":{"@context":{"const":"https://schema.org"},"@type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"dateModified":{"type":"string","format":"date"},"encoding":{"type":"object"}}}},"limitations":{"type":"string"},"pagination":{"type":"object","required":["total","limit","offset","has_more","next_offset"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"},"next_offset":{"type":["integer","null"]}}}}}}},"headers":{"Link":{"description":"Link to the versioning and retirement policy with rel=deprecation; this does not mark an active operation deprecated.","schema":{"type":"string"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the per-instance window resets.","schema":{"type":"integer"}}}},"400":{"description":"Invalid or repeated pagination parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"REST error envelope for a rejected request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/pages/batch":{"post":{"operationId":"getPagesBatch","summary":"Retrieve metadata and source links for up to 20 published pages","description":"Read-only batch lookup. Responses preserve request order. Unknown paths produce per-item 404 errors while valid pages still return metadata. Invalid envelopes, duplicate paths and non-relative paths fail with 400. Does not fetch arbitrary URLs, return full article bodies or store inputs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["paths"],"additionalProperties":false,"properties":{"paths":{"type":"array","minItems":1,"maxItems":20,"uniqueItems":true,"items":{"type":"string","maxLength":300,"pattern":"^/(?!/)[a-z0-9/-]*$"}}}}}}},"responses":{"200":{"description":"Ordered per-item page metadata or NOT_FOUND results.","content":{"application/json":{"schema":{"type":"object","required":["results","limitations"],"properties":{"results":{"type":"array","items":{"oneOf":[{"type":"object","required":["path","status","page"],"properties":{"path":{"type":"string"},"status":{"const":200},"page":{"type":"object","required":["name","description","url","dateModified"],"properties":{"@context":{"const":"https://schema.org"},"@type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"dateModified":{"type":"string","format":"date"},"encoding":{"type":"object"}}}}},{"type":"object","required":["path","status","error"],"properties":{"path":{"type":"string"},"status":{"const":404},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_ARGUMENT","NOT_FOUND","RATE_LIMITED","INVALID_IDEMPOTENCY_KEY","IDEMPOTENCY_MISMATCH"]},"message":{"type":"string"}}}}}]}},"limitations":{"type":"string"}}}}},"headers":{"Link":{"description":"Link to the versioning and retirement policy with rel=deprecation; this does not mark an active operation deprecated.","schema":{"type":"string"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the per-instance window resets.","schema":{"type":"integer"}}}},"400":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-instance request window exhausted. Retry after the indicated delay; this is not a global quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Link":{"description":"Link to the versioning and retirement policy with rel=deprecation; this does not mark an active operation deprecated.","schema":{"type":"string"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the per-instance window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Window reset as Unix seconds.","schema":{"type":"integer"}}}}}}},"/api/v1/calculate":{"post":{"operationId":"calculate","summary":"Run an educational calculator without saving inputs","description":"Pure v1 calculation with optional content-bound Idempotency-Key. See the developer idempotency policy for the canonical compact JSON hash. Same canonical inputs yield identical results across retries and instances; keys and inputs are never stored. Malformed keys return 400; changed inputs with the same key return 422.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional structured string: a quoted sha256:<64 lowercase hex> digest of the canonical request. No time-based expiry within v1. See /developers#idempotency.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["calculation","parameters"],"properties":{"calculation":{"const":"weight_memory"},"parameters":{"type":"object","properties":{"parameters_billions":{"type":"number","exclusiveMinimum":0},"bits":{"type":"number","enum":[4,8,16,32]}},"required":["parameters_billions","bits"],"additionalProperties":false}},"additionalProperties":false},{"type":"object","required":["calculation","parameters"],"properties":{"calculation":{"const":"facility_energy"},"parameters":{"type":"object","properties":{"it_kw":{"type":"number","minimum":0},"pue":{"type":"number","minimum":1},"hours":{"type":"number","minimum":0},"usd_per_kwh":{"type":"number","minimum":0}},"required":["it_kw","pue","hours","usd_per_kwh"],"additionalProperties":false}},"additionalProperties":false},{"type":"object","required":["calculation","parameters"],"properties":{"calculation":{"const":"token_cost"},"parameters":{"type":"object","properties":{"cost_usd":{"type":"number","minimum":0},"completed_tokens":{"type":"number","exclusiveMinimum":0}},"required":["cost_usd","completed_tokens"],"additionalProperties":false}},"additionalProperties":false}]}}}},"responses":{"200":{"description":"Illustrative estimate with supplied inputs, units and limitations.","content":{"application/json":{"schema":{"type":"object","required":["calculation","inputs","result","limitations"],"properties":{"calculation":{"type":"string"},"inputs":{"type":"object"},"result":{"type":"object"},"limitations":{"type":"string"}}}}},"headers":{"Link":{"description":"Link to the versioning and retirement policy with rel=deprecation; this does not mark an active operation deprecated.","schema":{"type":"string"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the per-instance window resets.","schema":{"type":"integer"}}}},"400":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Invalid request, disallowed Origin, oversized body or unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key does not match the canonical calculator inputs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-instance request window exhausted. Retry after the indicated delay; this is not a global quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Link":{"description":"Link to the versioning and retirement policy with rel=deprecation; this does not mark an active operation deprecated.","schema":{"type":"string"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the per-instance window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Window reset as Unix seconds.","schema":{"type":"integer"}}}}}}},"/ask":{"post":{"operationId":"searchPages","summary":"NLWeb 0.55 list-mode search over published page descriptions","description":"Deterministic title/description search; no generated answers. Application failures, including NO_RESULTS, use HTTP 200 with response_type=failure. SSE uses start, result, error and complete events.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":2000},"site":{"type":"string"}},"additionalProperties":false},"context":{"type":"object","description":"Accepted for protocol compatibility; not used for matching or retained."},"prefer":{"type":"object","properties":{"mode":{"const":"list","default":"list"},"response_format":{"const":"conversational_search"},"streaming":{"type":"boolean","default":false},"limit":{"type":"integer","minimum":1,"maximum":20,"default":5}}},"meta":{"type":"object","properties":{"version":{"const":"0.55"}},"description":"Metadata is not retained."}}}}}},"responses":{"200":{"description":"Published references, NLWeb failure, or SSE event stream.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["_meta","results"],"properties":{"_meta":{"type":"object","properties":{"response_type":{"const":"answer"},"version":{"const":"0.55"}}},"results":{"type":"array","items":{"type":"object","required":["name","description","url","dateModified"],"properties":{"@context":{"const":"https://schema.org"},"@type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"dateModified":{"type":"string","format":"date"},"encoding":{"type":"object"}}}}}},{"type":"object","required":["_meta","error"],"properties":{"_meta":{"type":"object","required":["response_type","version"],"properties":{"response_type":{"const":"failure"},"version":{"const":"0.55"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}]}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Request rejected before query execution.","content":{"application/json":{"schema":{"type":"object","required":["_meta","error"],"properties":{"_meta":{"type":"object","required":["response_type","version"],"properties":{"response_type":{"const":"failure"},"version":{"const":"0.55"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"403":{"description":"Request rejected before query execution.","content":{"application/json":{"schema":{"type":"object","required":["_meta","error"],"properties":{"_meta":{"type":"object","required":["response_type","version"],"properties":{"response_type":{"const":"failure"},"version":{"const":"0.55"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"413":{"description":"Request rejected before query execution.","content":{"application/json":{"schema":{"type":"object","required":["_meta","error"],"properties":{"_meta":{"type":"object","required":["response_type","version"],"properties":{"response_type":{"const":"failure"},"version":{"const":"0.55"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"415":{"description":"Request rejected before query execution.","content":{"application/json":{"schema":{"type":"object","required":["_meta","error"],"properties":{"_meta":{"type":"object","required":["response_type","version"],"properties":{"response_type":{"const":"failure"},"version":{"const":"0.55"}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}}}