{"openapi":"3.1.0","info":{"title":"Grail Computer Public Discovery API","version":"1.0.0","description":"Unhappy with your software vendor’s speed? Grail engineers take over stuck software, rebuild what is broken and keep it moving. This read-only API uses URL-path versions. Deprecated aliases remain available with RFC 9745 Deprecation and successor-version Link headers; breaking versions receive a documented migration window before Sunset."},"externalDocs":{"description":"Grail Computer developer resources and API lifecycle policy","url":"https://grail.computer/developers"},"security":[],"servers":[{"url":"https://grail.computer","description":"Grail Computer production public API"}],"paths":{"/api/v1/nlweb/search":{"get":{"operationId":"searchGrailComputerPublicContentV1","summary":"Search public Grail Computer content","description":"Search public Grail Computer pages covering managed software takeover, delivery, the Software Factory, supporting capabilities, and case studies. Results use opaque cursor pagination.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Search query. An empty query returns the public index."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10},"description":"Maximum number of results in this page."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque nextCursor value returned by the preceding response."}],"responses":{"200":{"description":"A page of ranked public Grail Computer content.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"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/SearchResponse"}}}},"400":{"description":"A query parameter or JSON request body is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"405":{"description":"The HTTP method is not supported for this route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"The public per-client request quota has been exhausted.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The server could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/nlweb/ask":{"get":{"operationId":"answerGrailComputerPublicQuestionV1","summary":"Answer a question from public Grail Computer sources","description":"Return a concise answer, ranked results, and source URLs from the public Grail Computer content index.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Question or search query."}],"responses":{"200":{"description":"A grounded answer and its public sources.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"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/AnswerResponse"}}}},"400":{"description":"A query parameter or JSON request body is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"405":{"description":"The HTTP method is not supported for this route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"The public per-client request quota has been exhausted.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The server could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/nlweb/search":{"get":{"operationId":"searchGrailComputerPublicContentLegacy","summary":"Search public Grail Computer content","description":"Deprecated compatibility alias. Use GET /api/v1/nlweb/search. Grail signals deprecated HTTP endpoints with Deprecation and successor-version Link headers before removal.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Search query. An empty query returns the public index."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10},"description":"Maximum number of results in this page."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque nextCursor value returned by the preceding response."}],"responses":{"200":{"description":"A page of ranked public Grail Computer content.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"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/SearchResponse"}}}},"400":{"description":"A query parameter or JSON request body is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"405":{"description":"The HTTP method is not supported for this route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"The public per-client request quota has been exhausted.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The server could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"deprecated":true}},"/api/nlweb/ask":{"get":{"operationId":"answerGrailComputerPublicQuestionLegacy","summary":"Answer a question from public Grail Computer sources","description":"Deprecated compatibility alias. Use GET /api/v1/nlweb/ask. Grail signals deprecated HTTP endpoints with Deprecation and successor-version Link headers before removal.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Question or search query."}],"responses":{"200":{"description":"A grounded answer and its public sources.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"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/AnswerResponse"}}}},"400":{"description":"A query parameter or JSON request body is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"405":{"description":"The HTTP method is not supported for this route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"The public per-client request quota has been exhausted.","headers":{"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The server could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"deprecated":true}}},"components":{"headers":{"RateLimitPolicy":{"description":"Quota policy in the IETF RateLimit structured-field format.","schema":{"type":"string"}},"RateLimit":{"description":"Current request quota and reset time using the IETF RateLimit structured field.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Compatibility form of the request quota.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Compatibility form of the remaining request quota.","schema":{"type":"integer"}},"RateLimitReset":{"description":"Seconds until the current quota window resets.","schema":{"type":"integer"}}},"responses":{"BadRequest":{"description":"A query parameter or JSON request body is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"MethodNotAllowed":{"description":"The HTTP method is not supported for this route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"The public per-client request quota has been exhausted.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}},"RateLimit":{"$ref":"#/components/headers/RateLimit"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalError":{"description":"The server could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable error summary."},"resolution":{"type":"string","description":"Specific recovery guidance."}},"required":["code","message","resolution"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"DiscoveryResult":{"type":"object","properties":{"path":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"score":{"type":"number"}},"required":["path","url","title","description","category","score"],"additionalProperties":false},"SearchResponse":{"type":"object","properties":{"query":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/DiscoveryResult"}},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page, or null."}},"required":["query","results","nextCursor"],"additionalProperties":false},"AnswerMeta":{"type":"object","properties":{"response_type":{"type":"string","const":"answer"},"version":{"type":"string","const":"1.0"}},"required":["response_type","version"],"additionalProperties":false},"AnswerResponse":{"type":"object","properties":{"_meta":{"$ref":"#/components/schemas/AnswerMeta"},"query":{"type":"string"},"answer":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/DiscoveryResult"}},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["title","url"],"additionalProperties":false}}},"required":["_meta","query","answer","results","sources"],"additionalProperties":false}}}}