{"openapi":"3.1.1","info":{"title":"XeoPulse agent API","version":"1.0.0-beta","description":"Assess supplied public observations for signal strength, contradictions and the next validation step. Does not crawl, verify sources, predict demand or establish market validation."},"servers":[{"url":"https://www.xeopulse.app"}],"security":[{"BetaKey":[]}],"paths":{"/api/v1/assess":{"post":{"operationId":"assess_demand_signal","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Input"},"example":{"market":"Synthetic agent tooling","problem":"Teams report difficulty comparing agent services.","evidenceWindow":"30","tier":"pain","velocity":"steady","density":"medium","observations":[{"sourceUrl":"https://example.com/a","observedDate":"2026-09-05","excerpt":"Synthetic observation describing a comparison difficulty.","sourceType":"forum","strength":2,"position":"supporting"},{"sourceUrl":"https://example.org/b","observedDate":"2026-09-05","excerpt":"Synthetic review describing the same public problem.","sourceType":"review","strength":2,"position":"supporting"},{"sourceUrl":"https://example.net/c","observedDate":"2026-09-05","excerpt":"Synthetic counterexample describing an adequate solution.","sourceType":"other","strength":1,"position":"contradicting"}]}}}},"responses":{"200":{"description":"Validated result from the original engine; no authority or procurement is implied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Output"}}}},"400":{"description":"Sanitized error. Respect Retry-After on 429/503; a daily cap resets at the next UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sanitized error. Respect Retry-After on 429/503; a daily cap resets at the next UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Sanitized error. Respect Retry-After on 429/503; a daily cap resets at the next UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Sanitized error. Respect Retry-After on 429/503; a daily cap resets at the next UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Sanitized error. Respect Retry-After on 429/503; a daily cap resets at the next UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Sanitized error. Respect Retry-After on 429/503; a daily cap resets at the next UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Sanitized error. Respect Retry-After on 429/503; a daily cap resets at the next UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Sanitized error. Respect Retry-After on 429/503; a daily cap resets at the next UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Sanitized error. Respect Retry-After on 429/503; a daily cap resets at the next UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Sanitized error. Respect Retry-After on 429/503; a daily cap resets at the next UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Sanitized error. Respect Retry-After on 429/503; a daily cap resets at the next UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Sanitized error. Respect Retry-After on 429/503; a daily cap resets at the next UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Sanitized error. Respect Retry-After on 429/503; a daily cap resets at the next UTC day.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"BetaKey":{"type":"apiKey","in":"header","name":"X-Agent-API-Key"}},"schemas":{"Input":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://xeopulse.app/schemas/request.schema.json","type":"object","required":["market","problem","evidenceWindow","tier","velocity","density","observations"],"properties":{"market":{"type":"string","minLength":2,"maxLength":120,"pattern":"^\\S(?:[\\s\\S]*\\S)?$"},"problem":{"type":"string","minLength":10,"maxLength":500,"pattern":"^\\S(?:[\\s\\S]*\\S)?$"},"evidenceWindow":{"enum":["30","90","180"]},"tier":{"enum":["pain","workaround","migration"]},"velocity":{"enum":["rising","steady","declining","unknown"]},"density":{"enum":["low","medium","high","unknown"]},"observations":{"type":"array","minItems":3,"maxItems":10,"items":{"type":"object","required":["sourceUrl","observedDate","excerpt","sourceType","strength","position"],"properties":{"sourceUrl":{"type":"string","format":"uri","pattern":"^[hH][tT][tT][pP][sS]?://(?![^/?#]*@)(?![^/?#]*%)(?![^/?#]*:)(?!\\[)(?![^/?#]*\\.\\.)(?!0[xX][0-9A-Fa-f]+(?:[./?#]|$))(?![^/?#]*\\.0[xX][0-9A-Fa-f]+(?:[./?#]|$))(?=[^/?#:]*[A-Za-z\\u0080-\\uFFFF])(?=[^/?#:]+\\.[^/?#:]+(?:[/?#]|$))(?!(?:[lL][oO][cC][aA][lL][hH][oO][sS][tT]|[^/?#:]+\\.(?:[lL][oO][cC][aA][lL][hH][oO][sS][tT]|[lL][oO][cC][aA][lL]|[iI][nN][tT][eE][rR][nN][aA][lL]|[lL][aA][nN]))(?:[/?#]|$)).+","maxLength":500,"description":"Public HTTP(S) URL with a DNS host and no credentials or explicit port; IP literals, encoded hosts, local names, empty labels and private-network suffixes are rejected. Runtime performs final URL normalization and validation."},"observedDate":{"type":"string","format":"date","description":"Must not be in the future or outside evidenceWindow."},"excerpt":{"type":"string","minLength":8,"maxLength":500,"pattern":"^\\S(?:[\\s\\S]*\\S)?$"},"sourceType":{"enum":["forum","review","search","marketplace","other"]},"strength":{"enum":[1,2,3]},"position":{"enum":["supporting","contradicting"]}},"additionalProperties":false}}},"additionalProperties":false},"Output":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://xeopulse.app/schemas/opportunity-packet.v1.json","title":"XeoPulse opportunity packet v1","type":"object","required":["schemaVersion","ruleset","assessedOn","outcome","score","confidence","components","observations","inferences","contradictions","missingEvidence","nextStep","input","caveat"],"properties":{"schemaVersion":{"const":"xeopulse.opportunity-packet.v1"},"ruleset":{"const":"xeopulse-assessor-2026-09-04"},"assessedOn":{"type":"string","format":"date"},"outcome":{"enum":["VALIDATE NEXT","EVIDENCE INCOMPLETE","CROWDED — DIFFERENTIATE","SIGNAL DECLINING — RECHECK"]},"score":{"type":"integer","minimum":0,"maximum":100},"confidence":{"enum":["LOW","MEDIUM","HIGH"]},"components":{"type":"object","required":["evidence","coverage","velocity","solutionDensity","contradictionPenalty","tierWeight"],"properties":{"evidence":{"type":"integer","minimum":0,"maximum":68},"coverage":{"type":"integer","minimum":0,"maximum":20},"velocity":{"type":"integer","minimum":0,"maximum":18},"solutionDensity":{"type":"integer","minimum":0,"maximum":12},"contradictionPenalty":{"type":"integer","minimum":0,"maximum":20},"tierWeight":{"enum":[1,1.3,1.5]}},"additionalProperties":false},"observations":{"type":"array","minItems":3,"maxItems":10,"items":{"$ref":"#/$defs/observation"}},"inferences":{"type":"array","items":{"type":"string"}},"contradictions":{"type":"array","items":{"$ref":"#/$defs/contradiction"}},"missingEvidence":{"type":"array","items":{"type":"string"}},"nextStep":{"type":"string"},"input":{"type":"object","required":["market","problem","evidenceWindow","tier","velocity","density"],"properties":{"market":{"type":"string"},"problem":{"type":"string"},"evidenceWindow":{"enum":["30","90","180"]},"tier":{"enum":["pain","workaround","migration"]},"velocity":{"enum":["rising","steady","declining","unknown"]},"density":{"enum":["low","medium","high","unknown"]}},"additionalProperties":false},"caveat":{"type":"string"}},"$defs":{"observation":{"type":"object","required":["sourceUrl","observedDate","excerpt","sourceType","strength","position"],"properties":{"sourceUrl":{"type":"string","format":"uri","pattern":"^[hH][tT][tT][pP][sS]?://"},"observedDate":{"type":"string","format":"date"},"excerpt":{"type":"string"},"sourceType":{"enum":["forum","review","search","marketplace","other"]},"strength":{"enum":[1,2,3]},"position":{"enum":["supporting","contradicting"]}},"additionalProperties":false},"contradiction":{"type":"object","required":["sourceUrl","observedDate","excerpt"],"properties":{"sourceUrl":{"type":"string","format":"uri","pattern":"^[hH][tT][tT][pP][sS]?://"},"observedDate":{"type":"string","format":"date"},"excerpt":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"Error":{"type":"object","required":["schema","error"],"additionalProperties":false,"properties":{"schema":{"const":"microsite.endpoint-error.v1"},"error":{"type":"object","required":["code","message","retryable","issues"],"additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"issues":{"type":"array","items":{"type":"object","required":["path","code"],"additionalProperties":false,"properties":{"path":{"type":"string"},"code":{"type":"string"}}}}}}}}}},"x-limits":{"inputBytes":65536,"outputBytes":262144,"jsonDepth":12,"bodyMs":5000,"analysisMs":3000,"concurrency":2,"sharedRequestsPerMinute":30,"sharedRequestsPerUtcDay":500,"concurrencyScope":"per isolate"},"x-privacy":"Public/synthetic inputs only. Transient server processing, no application input/output logs or storage. One aggregate quota row is persisted; hosting metadata may be processed."}