{"openapi":"3.1.0","info":{"title":"Recalled API","version":"v1","description":"API-first AI visibility measurement. Every successful and error response uses the Recalled agent envelope."},"servers":[{"url":"https://recalled.so"}],"paths":{"/api/v1/account/profile":{"get":{"summary":"Read your own profile name (session only)","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Update your own profile name (session only)","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"name":"x-profile-session","in":"header","required":true,"schema":{"type":"string"},"description":"Session scope returned by the profile read."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expectedFullName","fullName"],"properties":{"expectedFullName":{"type":["string","null"]},"fullName":{"type":["string","null"],"maxLength":120}}}}}}}},"/api/v1/enrichments":{"get":{"summary":"List up to 50 recent organization enrichments","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Read a public site and save sourced comparison and question suggestions, not measured demand; without model calls","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048}},"required":["url"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/batch":{"post":{"summary":"Read up to 50 enrichments; missing or other-tenant ids return null","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/{enrichmentId}":{"parameters":[{"name":"enrichmentId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read an enrichment and its confirmation revision","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Save and explicitly confirm one step","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"step":{"type":"string","enum":["brand","aliases","competitors","topics","prompts"]},"confirmation":{"type":"object","properties":{"brand":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"category":{"type":"string","maxLength":2000},"oneLiner":{"type":"string","maxLength":2000},"audience":{"type":"string","maxLength":2000},"positioning":{"type":"string","maxLength":2000}},"required":["name","category","oneLiner","audience","positioning"],"additionalProperties":false},"profile":{"type":"object","properties":{"insights":{"type":"object","properties":{"offerings":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":500},"benefits":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}}},"required":["name","description","benefits"],"additionalProperties":false}},"audiences":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"segment":{"type":"string","minLength":1,"maxLength":500},"roles":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}}},"required":["segment","roles"],"additionalProperties":false}},"needs":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"need":{"type":"string","minLength":1,"maxLength":500},"solution":{"type":"string","minLength":1,"maxLength":500}},"required":["need","solution"],"additionalProperties":false}},"positioning":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500}},"required":["value"],"additionalProperties":false}},"topics":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":200}},"required":["value"],"additionalProperties":false}},"questions":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"topic":{"type":"string","minLength":1,"maxLength":200},"intent":{"type":"string","enum":["discovery","use_case","evaluation","comparison"]}},"required":["value","topic","intent"],"additionalProperties":false}}},"required":["offerings","audiences","needs","positioning","topics","questions"],"additionalProperties":false},"version":{"type":"number","const":1},"extractionId":{"type":"string","minLength":1,"maxLength":200},"offerings":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"useCases":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"differentiators":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"market":{"anyOf":[{"type":"object","properties":{"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"}},"required":["locationCode","languageCode"],"additionalProperties":false},{"type":"null"}]}},"required":["version","offerings","useCases","differentiators","market"],"additionalProperties":false},"aliases":{"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"competitors":{"maxItems":5,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"domain":{"type":"string","maxLength":253},"suggestionId":{"type":"string","pattern":"^[a-f0-9]{64}$"},"discoveryId":{"type":"string","minLength":1},"candidateId":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["name","domain"],"additionalProperties":false}},"topics":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"prompts":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000},"topic":{"type":"string","maxLength":200},"branded":{"type":"boolean"},"suggestionId":{"type":"string","pattern":"^[a-f0-9]{64}$"},"engines":{"minItems":1,"maxItems":4,"type":"array","items":{"type":"string","enum":["chatgpt","perplexity","deepseek","google_aio"]}}},"required":["text","topic","branded","engines"],"additionalProperties":false}}},"required":["brand","aliases","competitors","topics","prompts"],"additionalProperties":false}},"required":["expectedRevision","step","confirmation"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/{enrichmentId}/buyer-questions":{"parameters":[{"name":"enrichmentId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read saved inferred buyer questions and confirmed context without spending","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"preparation":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["sent","completed","incomplete","unknown","stale"]},"contextHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"contextReferences":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"value":{"type":"string"}},"required":["id","path","value"],"additionalProperties":false}},"questions":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":500},"topic":{"type":"string","minLength":1,"maxLength":200},"intent":{"type":"string","enum":["discovery","use_case","evaluation","comparison"]},"audience":{"type":"string","minLength":1,"maxLength":200},"perspective":{"type":"string","minLength":1,"maxLength":200},"rationale":{"type":"string","minLength":1,"maxLength":500},"contextRefs":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","pattern":"^c[1-9]\\d{0,2}$"}},"id":{"type":"string","pattern":"^[a-f0-9]{64}$"},"basis":{"type":"string","const":"confirmed_context_inference"}},"required":["text","topic","intent","audience","perspective","rationale","contextRefs","id","basis"],"additionalProperties":false}},"example":{"type":"boolean","const":false}},"required":["id","status","contextHash","contextReferences","questions","example"],"additionalProperties":false},{"type":"null"}]}},"required":["preparation"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Prepare buyer questions once for confirmed business and competitor context; no scans or answer allowance","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"preparation":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["sent","completed","incomplete","unknown","stale"]},"contextHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"contextReferences":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string"},"value":{"type":"string"}},"required":["id","path","value"],"additionalProperties":false}},"questions":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":500},"topic":{"type":"string","minLength":1,"maxLength":200},"intent":{"type":"string","enum":["discovery","use_case","evaluation","comparison"]},"audience":{"type":"string","minLength":1,"maxLength":200},"perspective":{"type":"string","minLength":1,"maxLength":200},"rationale":{"type":"string","minLength":1,"maxLength":500},"contextRefs":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","pattern":"^c[1-9]\\d{0,2}$"}},"id":{"type":"string","pattern":"^[a-f0-9]{64}$"},"basis":{"type":"string","const":"confirmed_context_inference"}},"required":["text","topic","intent","audience","perspective","rationale","contextRefs","id","basis"],"additionalProperties":false}},"example":{"type":"boolean","const":false}},"required":["id","status","contextHash","contextReferences","questions","example"],"additionalProperties":false},{"type":"null"}]}},"required":["preparation"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/{enrichmentId}/competitor-discovery":{"parameters":[{"name":"enrichmentId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read saved inferred competitor suggestions","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Prepare reviewable competitor suggestions once for this draft","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/{enrichmentId}/discovery/markets":{"parameters":[{"name":"enrichmentId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read the free provider country and language catalogue without paid research","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/profile/capabilities":{"get":{"summary":"Read analysis readiness, allowance and provider policy before capturing a website","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"capabilities":{"type":"object","properties":{"available":{"type":"boolean"},"reason":{"anyOf":[{"type":"string","enum":["rate_expired","unavailable","quota_exceeded","storage_exceeded"]},{"type":"null"}]},"policyFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"rateExpiresAt":{"type":"string"},"model":{"type":"string"},"example":{"type":"boolean"},"quota":{"type":"object","properties":{"websites":{"type":"object","properties":{"limit":{"type":"integer","minimum":0,"maximum":9007199254740991},"used":{"type":"integer","minimum":0,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":0,"maximum":9007199254740991},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["limit","used","remaining"],"additionalProperties":false}},"required":["websites"],"additionalProperties":false},"delta":{"type":"object","properties":{"analysisAttempts":{"type":"number","const":1},"answerUnits":{"type":"number","const":0}},"required":["analysisAttempts","answerUnits"],"additionalProperties":false},"customerCharge":{"type":"number","const":0},"notice":{"type":"string"}},"required":["available","reason","policyFingerprint","rateExpiresAt","model","example","quota","delta","customerCharge","notice"],"additionalProperties":false}},"required":["capabilities"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/{enrichmentId}/profile/preview":{"parameters":[{"name":"enrichmentId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Preview inferred business profile analysis without a provider request","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"preview":{"type":"object","properties":{"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"fingerprint":{"type":"string"},"model":{"type":"string"},"rateSource":{"type":"string"},"inputByteLimit":{"type":"integer","minimum":0,"maximum":9007199254740991},"outputTokenLimit":{"type":"integer","minimum":0,"maximum":9007199254740991},"rateExpiresAt":{"type":"string"},"quota":{"type":"object","properties":{"websites":{"type":"object","properties":{"limit":{"type":"integer","minimum":0,"maximum":9007199254740991},"used":{"type":"integer","minimum":0,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":0,"maximum":9007199254740991},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["limit","used","remaining"],"additionalProperties":false}},"required":["websites"],"additionalProperties":false},"example":{"type":"boolean"},"allowed":{"type":"boolean"},"reason":{"anyOf":[{"type":"string","enum":["already_attempted","quota_exceeded","storage_exceeded","rate_expired","unavailable"]},{"type":"null"}]},"notice":{"type":"string"}},"required":["revision","fingerprint","model","rateSource","inputByteLimit","outputTokenLimit","rateExpiresAt","quota","example","allowed","reason","notice"],"additionalProperties":false}},"required":["preview"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/{enrichmentId}/profile":{"parameters":[{"name":"enrichmentId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List saved profile attempts without dispatching analysis","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["sent","completed","incomplete","refused","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed"]},"billing":{"type":"string","enum":["bounded","unknown"]},"suggestions":{"anyOf":[{"type":"object","properties":{"category":{"maxItems":1,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"summary":{"maxItems":1,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"audiences":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"offerings":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"useCases":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"differentiators":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"insights":{"type":"object","properties":{"offerings":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":500},"benefits":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["name","description","benefits","evidence"],"additionalProperties":false}},"audiences":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"segment":{"type":"string","minLength":1,"maxLength":500},"roles":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["segment","roles","evidence"],"additionalProperties":false}},"needs":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"need":{"type":"string","minLength":1,"maxLength":500},"solution":{"type":"string","minLength":1,"maxLength":500},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["need","solution","evidence"],"additionalProperties":false}},"positioning":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["value","evidence"],"additionalProperties":false}},"topics":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":200},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["value","evidence"],"additionalProperties":false}},"questions":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"topic":{"type":"string","minLength":1,"maxLength":200},"intent":{"type":"string","enum":["discovery","use_case","evaluation","comparison"]},"basis":{"type":"string","const":"inferred"},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["value","topic","intent","basis","evidence"],"additionalProperties":false}}},"required":["offerings","audiences","needs","positioning","topics","questions"],"additionalProperties":false}},"required":["category","summary","audiences","offerings","useCases","differentiators"],"additionalProperties":false},{"type":"null"}]},"partialEvidence":{"type":"boolean"},"example":{"type":"boolean"},"receipt":{"anyOf":[{"type":"object","properties":{"responseId":{"anyOf":[{"type":"string"},{"type":"null"}]},"inputTokens":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"outputTokens":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["responseId","inputTokens","outputTokens","reason"],"additionalProperties":false},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"modelPolicy":{"anyOf":[{"type":"string"},{"type":"null"}]},"sources":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"fetchedAt":{"type":"string"}},"required":["url","fetchedAt"],"additionalProperties":false}},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"receivedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","quoteFingerprint","revision","status","reservationStatus","billing","suggestions","partialEvidence","example","receipt","responseHash","modelPolicy","sources","reason","createdAt","receivedAt"],"additionalProperties":false}}},"required":["attempts"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Analyze the exact preview with explicit consent; unknown outcomes remain held","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"quoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"consent":{"type":"object","properties":{"policyFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["policyFingerprint"],"additionalProperties":false}},"required":["expectedRevision","quoteFingerprint"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"attempt":{"type":"object","properties":{"id":{"type":"string"},"quoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["sent","completed","incomplete","refused","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed"]},"billing":{"type":"string","enum":["bounded","unknown"]},"suggestions":{"anyOf":[{"type":"object","properties":{"category":{"maxItems":1,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"summary":{"maxItems":1,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"audiences":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"offerings":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"useCases":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"differentiators":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"insights":{"type":"object","properties":{"offerings":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":500},"benefits":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["name","description","benefits","evidence"],"additionalProperties":false}},"audiences":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"segment":{"type":"string","minLength":1,"maxLength":500},"roles":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["segment","roles","evidence"],"additionalProperties":false}},"needs":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"need":{"type":"string","minLength":1,"maxLength":500},"solution":{"type":"string","minLength":1,"maxLength":500},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["need","solution","evidence"],"additionalProperties":false}},"positioning":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["value","evidence"],"additionalProperties":false}},"topics":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":200},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["value","evidence"],"additionalProperties":false}},"questions":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"topic":{"type":"string","minLength":1,"maxLength":200},"intent":{"type":"string","enum":["discovery","use_case","evaluation","comparison"]},"basis":{"type":"string","const":"inferred"},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["value","topic","intent","basis","evidence"],"additionalProperties":false}}},"required":["offerings","audiences","needs","positioning","topics","questions"],"additionalProperties":false}},"required":["category","summary","audiences","offerings","useCases","differentiators"],"additionalProperties":false},{"type":"null"}]},"partialEvidence":{"type":"boolean"},"example":{"type":"boolean"},"receipt":{"anyOf":[{"type":"object","properties":{"responseId":{"anyOf":[{"type":"string"},{"type":"null"}]},"inputTokens":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"outputTokens":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["responseId","inputTokens","outputTokens","reason"],"additionalProperties":false},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"modelPolicy":{"anyOf":[{"type":"string"},{"type":"null"}]},"sources":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"fetchedAt":{"type":"string"}},"required":["url","fetchedAt"],"additionalProperties":false}},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"receivedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","quoteFingerprint","revision","status","reservationStatus","billing","suggestions","partialEvidence","example","receipt","responseHash","modelPolicy","sources","reason","createdAt","receivedAt"],"additionalProperties":false}},"required":["attempt"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/{enrichmentId}/profile/batch":{"parameters":[{"name":"enrichmentId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read up to twenty profile attempts; unavailable IDs return null","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"quoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["sent","completed","incomplete","refused","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed"]},"billing":{"type":"string","enum":["bounded","unknown"]},"suggestions":{"anyOf":[{"type":"object","properties":{"category":{"maxItems":1,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"summary":{"maxItems":1,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"audiences":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"offerings":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"useCases":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"differentiators":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"insights":{"type":"object","properties":{"offerings":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":500},"benefits":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["name","description","benefits","evidence"],"additionalProperties":false}},"audiences":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"segment":{"type":"string","minLength":1,"maxLength":500},"roles":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["segment","roles","evidence"],"additionalProperties":false}},"needs":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"need":{"type":"string","minLength":1,"maxLength":500},"solution":{"type":"string","minLength":1,"maxLength":500},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["need","solution","evidence"],"additionalProperties":false}},"positioning":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["value","evidence"],"additionalProperties":false}},"topics":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":200},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["value","evidence"],"additionalProperties":false}},"questions":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"topic":{"type":"string","minLength":1,"maxLength":200},"intent":{"type":"string","enum":["discovery","use_case","evaluation","comparison"]},"basis":{"type":"string","const":"inferred"},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["value","topic","intent","basis","evidence"],"additionalProperties":false}}},"required":["offerings","audiences","needs","positioning","topics","questions"],"additionalProperties":false}},"required":["category","summary","audiences","offerings","useCases","differentiators"],"additionalProperties":false},{"type":"null"}]},"partialEvidence":{"type":"boolean"},"example":{"type":"boolean"},"receipt":{"anyOf":[{"type":"object","properties":{"responseId":{"anyOf":[{"type":"string"},{"type":"null"}]},"inputTokens":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"outputTokens":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["responseId","inputTokens","outputTokens","reason"],"additionalProperties":false},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"modelPolicy":{"anyOf":[{"type":"string"},{"type":"null"}]},"sources":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"fetchedAt":{"type":"string"}},"required":["url","fetchedAt"],"additionalProperties":false}},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"receivedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","quoteFingerprint","revision","status","reservationStatus","billing","suggestions","partialEvidence","example","receipt","responseHash","modelPolicy","sources","reason","createdAt","receivedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["id","attempt"],"additionalProperties":false}}},"required":["attempts"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/{enrichmentId}/profile/{attemptId}":{"parameters":[{"name":"enrichmentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"attemptId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read one saved profile attempt and its original website evidence","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"attempt":{"type":"object","properties":{"id":{"type":"string"},"quoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["sent","completed","incomplete","refused","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed"]},"billing":{"type":"string","enum":["bounded","unknown"]},"suggestions":{"anyOf":[{"type":"object","properties":{"category":{"maxItems":1,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"summary":{"maxItems":1,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"audiences":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"offerings":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"useCases":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"differentiators":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}},"insights":{"type":"object","properties":{"offerings":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":500},"benefits":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["name","description","benefits","evidence"],"additionalProperties":false}},"audiences":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"segment":{"type":"string","minLength":1,"maxLength":500},"roles":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["segment","roles","evidence"],"additionalProperties":false}},"needs":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"need":{"type":"string","minLength":1,"maxLength":500},"solution":{"type":"string","minLength":1,"maxLength":500},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["need","solution","evidence"],"additionalProperties":false}},"positioning":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["value","evidence"],"additionalProperties":false}},"topics":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":200},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["value","evidence"],"additionalProperties":false}},"questions":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"topic":{"type":"string","minLength":1,"maxLength":200},"intent":{"type":"string","enum":["discovery","use_case","evaluation","comparison"]},"basis":{"type":"string","const":"inferred"},"evidence":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":500},"url":{"type":"string","minLength":1,"maxLength":2048},"selector":{"type":"string","enum":["text","jsonLd"]},"excerpt":{"type":"string","minLength":1,"maxLength":500},"fetchedAt":{"type":"string","minLength":1,"maxLength":100}},"required":["value","url","selector","excerpt","fetchedAt"],"additionalProperties":false}}},"required":["value","topic","intent","basis","evidence"],"additionalProperties":false}}},"required":["offerings","audiences","needs","positioning","topics","questions"],"additionalProperties":false}},"required":["category","summary","audiences","offerings","useCases","differentiators"],"additionalProperties":false},{"type":"null"}]},"partialEvidence":{"type":"boolean"},"example":{"type":"boolean"},"receipt":{"anyOf":[{"type":"object","properties":{"responseId":{"anyOf":[{"type":"string"},{"type":"null"}]},"inputTokens":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"outputTokens":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["responseId","inputTokens","outputTokens","reason"],"additionalProperties":false},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"modelPolicy":{"anyOf":[{"type":"string"},{"type":"null"}]},"sources":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"fetchedAt":{"type":"string"}},"required":["url","fetchedAt"],"additionalProperties":false}},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"receivedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","quoteFingerprint","revision","status","reservationStatus","billing","suggestions","partialEvidence","example","receipt","responseHash","modelPolicy","sources","reason","createdAt","receivedAt"],"additionalProperties":false}},"required":["attempt"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/{enrichmentId}/discovery/preview":{"parameters":[{"name":"enrichmentId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Preview one bounded market search and allowance without paid acquisition","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"query":{"type":"string","minLength":2,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"}},"required":["expectedRevision","query","locationCode","languageCode"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/{enrichmentId}/discovery":{"parameters":[{"name":"enrichmentId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List the latest twenty saved market searches","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Acquire one explicitly consented preview; unresolved work is held and never automatically retried","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"input":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"query":{"type":"string","minLength":2,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"}},"required":["expectedRevision","query","locationCode","languageCode"],"additionalProperties":false},"quoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["input","quoteFingerprint"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/{enrichmentId}/discovery/batch":{"parameters":[{"name":"enrichmentId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read up to twenty saved searches; unavailable IDs return null","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/{enrichmentId}/discovery/{discoveryId}":{"parameters":[{"name":"enrichmentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"discoveryId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read a saved market search and its reviewable candidates","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/enrichments/{enrichmentId}/discovery/{discoveryId}/evidence":{"parameters":[{"name":"enrichmentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"discoveryId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read the bounded original supplier receipt and hash","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/audits":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"List up to 20 captured site audits","description":"Read-only derivation from immutable stored crawl evidence. No network collection or provider spend.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Captured audit evidence","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"audits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"status":{"type":"string","enum":["available","partial","evidence_unavailable"]},"checkVersion":{"type":"string","enum":["1","2","3","4"]},"counts":{"type":"object","properties":{"pass":{"type":"integer","minimum":0,"maximum":9007199254740991},"fail":{"type":"integer","minimum":0,"maximum":9007199254740991},"unknown":{"type":"integer","minimum":0,"maximum":9007199254740991},"run":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["pass","fail","unknown","run"],"additionalProperties":false},"pages":{"type":"integer","minimum":0,"maximum":9007199254740991},"source":{"type":"object","properties":{"kind":{"type":"string","enum":["confirmed_enrichment","audit_run"]},"seedUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string"},"confirmedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"crawlStatus":{"type":"string","enum":["complete","partial","blocked"]}},"required":["kind","seedUrl","createdAt","confirmedAt","crawlStatus"],"additionalProperties":false},"issueCounts":{"anyOf":[{"type":"object","properties":{"high":{"type":"integer","minimum":0,"maximum":9007199254740991},"medium":{"type":"integer","minimum":0,"maximum":9007199254740991},"low":{"type":"integer","minimum":0,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["high","medium","low","total"],"additionalProperties":false},{"type":"null"}]}},"required":["id","projectId","status","checkVersion","counts","pages","source","issueCounts"],"additionalProperties":false}},"limit":{"type":"number","const":20}},"required":["audits","limit"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Explicitly run or refresh the current project site audit","description":"Explicit capture of the current configured HTTPS site: at most 25 pages, 45 requests, 25 MiB and 45 seconds, including its robots.txt, sitemap and llms.txt, plus up to 5 free Chrome UX Report page-speed lookups. No provider or answer units. Confirm boundsVersion 1 and expectedDomain; retry with the same key.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedDomain":{"type":"string","minLength":1,"maxLength":253},"boundsVersion":{"type":"string","const":"1"}},"required":["expectedDomain","boundsVersion"],"additionalProperties":false}}}},"responses":{"201":{"description":"Captured audit evidence","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"audit":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"status":{"type":"string","enum":["available","partial","evidence_unavailable"]},"checkVersion":{"type":"string","enum":["1","2","3","4"]},"counts":{"type":"object","properties":{"pass":{"type":"integer","minimum":0,"maximum":9007199254740991},"fail":{"type":"integer","minimum":0,"maximum":9007199254740991},"unknown":{"type":"integer","minimum":0,"maximum":9007199254740991},"run":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["pass","fail","unknown","run"],"additionalProperties":false},"pages":{"type":"array","items":{"type":"object","properties":{"source":{"type":"object","properties":{"receipt":{"type":"object","properties":{"requestedUrl":{"type":"string"},"url":{"type":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"contentType":{"type":"string"},"sha256":{"type":"string"},"fetchedAt":{"type":"string"}},"required":["requestedUrl","url","status","contentType","sha256","fetchedAt"],"additionalProperties":false},"kind":{"type":"string","enum":["static_html","challenge","rate_limited","javascript_shell","unclassified"]},"title":{"type":"object","properties":{"value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"truncated":{"type":"boolean"}},"required":["value","truncated"],"additionalProperties":false},"description":{"type":"object","properties":{"value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"truncated":{"type":"boolean"}},"required":["value","truncated"],"additionalProperties":false},"canonical":{"type":"object","properties":{"declared":{"type":"object","properties":{"value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"truncated":{"type":"boolean"}},"required":["value","truncated"],"additionalProperties":false},"resolved":{"anyOf":[{"type":"string"},{"type":"null"}]},"count":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["declared","resolved","count"],"additionalProperties":false},"robotsMeta":{"type":"object","properties":{"entries":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"agent":{"type":"string"},"content":{"type":"string"}},"required":["agent","content"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["entries","truncated"],"additionalProperties":false},"robotsHeader":{"type":"object","properties":{"captured":{"type":"boolean"},"values":{"maxItems":20,"type":"array","items":{"type":"string"}},"truncated":{"type":"boolean"}},"required":["captured","values","truncated"],"additionalProperties":false},"headings":{"type":"object","properties":{"entries":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"level":{"type":"integer","minimum":1,"maximum":6},"text":{"type":"string"}},"required":["level","text"],"additionalProperties":false}},"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"h1Count":{"type":"integer","minimum":0,"maximum":9007199254740991},"truncated":{"type":"boolean"}},"required":["entries","count","h1Count","truncated"],"additionalProperties":false},"internalLinks":{"type":"object","properties":{"entries":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"text":{"type":"string"},"rel":{"type":"string"}},"required":["url","text","rel"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["entries","truncated"],"additionalProperties":false},"textCapture":{"type":"object","properties":{"version":{"type":"string","const":"1"},"status":{"type":"string","enum":["available","partial","unavailable"]},"blocks":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tag":{"type":"string","enum":["h1","h2","h3","h4","h5","h6","p","li"]},"text":{"type":"string"},"hash":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["id","tag","text","hash"],"additionalProperties":false}},"bytes":{"type":"integer","minimum":0,"maximum":16384},"hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"reason":{"anyOf":[{"type":"string","enum":["limited","no_text","capacity"]},{"type":"null"}]}},"required":["version","status","blocks","bytes","hash","reason"],"additionalProperties":false},"jsonLd":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"inspected":{"type":"integer","minimum":0,"maximum":9007199254740991},"scripts":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"status":{"type":"string","enum":["valid_json","invalid_json","external","too_large","budget_exhausted"]},"sha256":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}]}},"required":["status","sha256"],"additionalProperties":false}},"types":{"maxItems":32,"type":"array","items":{"type":"string"}},"incomplete":{"type":"boolean"}},"required":["count","inspected","scripts","types","incomplete"],"additionalProperties":false},"signals":{"type":"object","properties":{"content":{"type":"object","properties":{"wordCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"textHash":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["wordCount","textHash"],"additionalProperties":false},"images":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"missingAlt":{"type":"integer","minimum":0,"maximum":9007199254740991},"examples":{"maxItems":3,"type":"array","items":{"type":"string"}}},"required":["total","missingAlt","examples"],"additionalProperties":false},"viewport":{"type":"boolean"},"mixedContent":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"active":{"type":"integer","minimum":0,"maximum":9007199254740991},"examples":{"maxItems":3,"type":"array","items":{"type":"string"}}},"required":["count","active","examples"],"additionalProperties":false},"dates":{"type":"object","properties":{"published":{"anyOf":[{"type":"string"},{"type":"null"}]},"modified":{"anyOf":[{"type":"string"},{"type":"null"}]},"timeElement":{"type":"boolean"}},"required":["published","modified","timeElement"],"additionalProperties":false},"noSnippetAttribute":{"type":"integer","minimum":0,"maximum":9007199254740991},"social":{"type":"object","properties":{"ogImage":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogTitle":{"type":"boolean"},"ogDescription":{"type":"boolean"}},"required":["ogImage","ogTitle","ogDescription"],"additionalProperties":false},"linkedFrom":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"pages":{"maxItems":5,"type":"array","items":{"type":"string"}}},"required":["count","pages"],"additionalProperties":false}},"required":["content","images","viewport","dates","noSnippetAttribute","social","linkedFrom"],"additionalProperties":false}},"required":["receipt","kind","title","description","canonical","robotsMeta","robotsHeader","headings","internalLinks"],"additionalProperties":false},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]},"label":{"type":"string"},"status":{"type":"string","enum":["pass","fail","unknown"]},"evidence":{"type":"string"},"action":{"type":"string"},"informational":{"type":"boolean","const":true}},"required":["id","label","status","evidence","action"],"additionalProperties":false}}},"required":["source","checks"],"additionalProperties":false}},"source":{"type":"object","properties":{"kind":{"type":"string","enum":["confirmed_enrichment","audit_run"]},"seedUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string"},"confirmedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"crawlStatus":{"type":"string","enum":["complete","partial","blocked"]},"enrichmentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"issues":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"targetUrl":{"type":"string","format":"uri"}},"required":["url","code","message"],"additionalProperties":false}},"requests":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limits":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"provenance":{"type":"object","properties":{"model":{"type":"null"},"apiProvider":{"type":"null"},"requestMethod":{"type":"string","const":"http"},"analysisMethod":{"type":"string","const":"static_html"},"version":{"type":"string","const":"1"},"geoFocus":{"type":"null"},"durationMs":{"type":"number","minimum":0}},"required":["model","apiProvider","requestMethod","analysisMethod","version","geoFocus","durationMs"],"additionalProperties":false}},"required":["kind","seedUrl","createdAt","confirmedAt","crawlStatus","enrichmentId","issues","requests","bytes","limits","provenance"],"additionalProperties":false},"site":{"anyOf":[{"type":"object","properties":{"crawlerAccess":{"type":"object","properties":{"url":{"type":"string"},"observedAt":{"type":"string"},"robots":{"type":"string","enum":["found","not_found","unavailable"]},"agents":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"agent":{"type":"string","enum":["GPTBot","OAI-SearchBot","ChatGPT-User","ClaudeBot","Claude-SearchBot","PerplexityBot","Google-Extended","Googlebot"]},"allowed":{"type":"boolean"}},"required":["agent","allowed"],"additionalProperties":false}},"sitemap":{"type":"string","enum":["declared","found","not_found","unavailable"]},"llmsTxt":{"type":"string","enum":["found","not_found","unavailable"]}},"required":["url","observedAt","robots","agents","sitemap","llmsTxt"],"additionalProperties":false},"entity":{"type":"object","properties":{"url":{"type":"string"},"observedAt":{"type":"string"},"status":{"type":"string","enum":["checked","unavailable"]},"incomplete":{"type":"boolean"},"organization":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","maxLength":128},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"hasUrl":{"type":"boolean"},"hasLogo":{"type":"boolean"},"sameAsCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"profiles":{"maxItems":9,"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["linkedin","x","wikipedia","wikidata","crunchbase","github","youtube","facebook","instagram"]},"url":{"type":"string","maxLength":2048}},"required":["network","url"],"additionalProperties":false}}},"required":["type","name","hasUrl","hasLogo","sameAsCount","profiles"],"additionalProperties":false},{"type":"null"}]},"brandName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},"required":["url","observedAt","status","incomplete","organization","brandName"],"additionalProperties":false},"sitemap":{"type":"object","properties":{"urlCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"complete":{"type":"boolean"}},"required":["urlCount","complete"],"additionalProperties":false},"robotsBlocked":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"examples":{"maxItems":20,"type":"array","items":{"type":"string"}}},"required":["count","examples"],"additionalProperties":false},"brokenLinks":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"linkedFrom":{"maxItems":3,"type":"array","items":{"type":"string"}}},"required":["url","linkedFrom"],"additionalProperties":false}},"pageSpeed":{"type":"object","properties":{"source":{"type":"string","const":"crux"},"formFactor":{"type":"string","const":"all"},"checkedAt":{"type":"string"},"results":{"maxItems":5,"type":"array","items":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"outcome":{"type":"string","enum":["url","origin","no_data","unavailable"]},"period":{"anyOf":[{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}},"required":["first","last"],"additionalProperties":false},{"type":"null"}]},"lcpMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"inpMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"cls":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","outcome","period","lcpMs","inpMs","cls"],"additionalProperties":false}}},"required":["source","formFactor","checkedAt","results"],"additionalProperties":false},"sourceOrigin":{"type":"object","properties":{"requestedUrl":{"type":"string"},"canonicalUrl":{"type":"string"}},"required":["requestedUrl","canonicalUrl"],"additionalProperties":false}},"required":["crawlerAccess","entity"],"additionalProperties":false},{"type":"null"}]},"siteChecks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]},"label":{"type":"string"},"status":{"type":"string","enum":["pass","fail","unknown"]},"evidence":{"type":"string"},"action":{"type":"string"},"informational":{"type":"boolean","const":true},"url":{"type":"string"},"observedAt":{"type":"string"}},"required":["id","label","status","evidence","action","url","observedAt"],"additionalProperties":false}},"limitations":{"type":"array","items":{"type":"string"}}},"required":["id","projectId","status","checkVersion","counts","pages","source","siteChecks","limitations"],"additionalProperties":false}},"required":["audit"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/audits/{auditId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"auditId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Read an audit with page evidence and suggested actions","description":"Read-only derivation from immutable stored crawl evidence. No network collection or provider spend.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Captured audit evidence","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"audit":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"status":{"type":"string","enum":["available","partial","evidence_unavailable"]},"checkVersion":{"type":"string","enum":["1","2","3","4"]},"counts":{"type":"object","properties":{"pass":{"type":"integer","minimum":0,"maximum":9007199254740991},"fail":{"type":"integer","minimum":0,"maximum":9007199254740991},"unknown":{"type":"integer","minimum":0,"maximum":9007199254740991},"run":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["pass","fail","unknown","run"],"additionalProperties":false},"pages":{"type":"array","items":{"type":"object","properties":{"source":{"type":"object","properties":{"receipt":{"type":"object","properties":{"requestedUrl":{"type":"string"},"url":{"type":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"contentType":{"type":"string"},"sha256":{"type":"string"},"fetchedAt":{"type":"string"}},"required":["requestedUrl","url","status","contentType","sha256","fetchedAt"],"additionalProperties":false},"kind":{"type":"string","enum":["static_html","challenge","rate_limited","javascript_shell","unclassified"]},"title":{"type":"object","properties":{"value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"truncated":{"type":"boolean"}},"required":["value","truncated"],"additionalProperties":false},"description":{"type":"object","properties":{"value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"truncated":{"type":"boolean"}},"required":["value","truncated"],"additionalProperties":false},"canonical":{"type":"object","properties":{"declared":{"type":"object","properties":{"value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"truncated":{"type":"boolean"}},"required":["value","truncated"],"additionalProperties":false},"resolved":{"anyOf":[{"type":"string"},{"type":"null"}]},"count":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["declared","resolved","count"],"additionalProperties":false},"robotsMeta":{"type":"object","properties":{"entries":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"agent":{"type":"string"},"content":{"type":"string"}},"required":["agent","content"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["entries","truncated"],"additionalProperties":false},"robotsHeader":{"type":"object","properties":{"captured":{"type":"boolean"},"values":{"maxItems":20,"type":"array","items":{"type":"string"}},"truncated":{"type":"boolean"}},"required":["captured","values","truncated"],"additionalProperties":false},"headings":{"type":"object","properties":{"entries":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"level":{"type":"integer","minimum":1,"maximum":6},"text":{"type":"string"}},"required":["level","text"],"additionalProperties":false}},"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"h1Count":{"type":"integer","minimum":0,"maximum":9007199254740991},"truncated":{"type":"boolean"}},"required":["entries","count","h1Count","truncated"],"additionalProperties":false},"internalLinks":{"type":"object","properties":{"entries":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"text":{"type":"string"},"rel":{"type":"string"}},"required":["url","text","rel"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["entries","truncated"],"additionalProperties":false},"textCapture":{"type":"object","properties":{"version":{"type":"string","const":"1"},"status":{"type":"string","enum":["available","partial","unavailable"]},"blocks":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tag":{"type":"string","enum":["h1","h2","h3","h4","h5","h6","p","li"]},"text":{"type":"string"},"hash":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["id","tag","text","hash"],"additionalProperties":false}},"bytes":{"type":"integer","minimum":0,"maximum":16384},"hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"reason":{"anyOf":[{"type":"string","enum":["limited","no_text","capacity"]},{"type":"null"}]}},"required":["version","status","blocks","bytes","hash","reason"],"additionalProperties":false},"jsonLd":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"inspected":{"type":"integer","minimum":0,"maximum":9007199254740991},"scripts":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"status":{"type":"string","enum":["valid_json","invalid_json","external","too_large","budget_exhausted"]},"sha256":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}]}},"required":["status","sha256"],"additionalProperties":false}},"types":{"maxItems":32,"type":"array","items":{"type":"string"}},"incomplete":{"type":"boolean"}},"required":["count","inspected","scripts","types","incomplete"],"additionalProperties":false},"signals":{"type":"object","properties":{"content":{"type":"object","properties":{"wordCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"textHash":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["wordCount","textHash"],"additionalProperties":false},"images":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"missingAlt":{"type":"integer","minimum":0,"maximum":9007199254740991},"examples":{"maxItems":3,"type":"array","items":{"type":"string"}}},"required":["total","missingAlt","examples"],"additionalProperties":false},"viewport":{"type":"boolean"},"mixedContent":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"active":{"type":"integer","minimum":0,"maximum":9007199254740991},"examples":{"maxItems":3,"type":"array","items":{"type":"string"}}},"required":["count","active","examples"],"additionalProperties":false},"dates":{"type":"object","properties":{"published":{"anyOf":[{"type":"string"},{"type":"null"}]},"modified":{"anyOf":[{"type":"string"},{"type":"null"}]},"timeElement":{"type":"boolean"}},"required":["published","modified","timeElement"],"additionalProperties":false},"noSnippetAttribute":{"type":"integer","minimum":0,"maximum":9007199254740991},"social":{"type":"object","properties":{"ogImage":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogTitle":{"type":"boolean"},"ogDescription":{"type":"boolean"}},"required":["ogImage","ogTitle","ogDescription"],"additionalProperties":false},"linkedFrom":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"pages":{"maxItems":5,"type":"array","items":{"type":"string"}}},"required":["count","pages"],"additionalProperties":false}},"required":["content","images","viewport","dates","noSnippetAttribute","social","linkedFrom"],"additionalProperties":false}},"required":["receipt","kind","title","description","canonical","robotsMeta","robotsHeader","headings","internalLinks"],"additionalProperties":false},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]},"label":{"type":"string"},"status":{"type":"string","enum":["pass","fail","unknown"]},"evidence":{"type":"string"},"action":{"type":"string"},"informational":{"type":"boolean","const":true}},"required":["id","label","status","evidence","action"],"additionalProperties":false}}},"required":["source","checks"],"additionalProperties":false}},"source":{"type":"object","properties":{"kind":{"type":"string","enum":["confirmed_enrichment","audit_run"]},"seedUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string"},"confirmedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"crawlStatus":{"type":"string","enum":["complete","partial","blocked"]},"enrichmentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"issues":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"targetUrl":{"type":"string","format":"uri"}},"required":["url","code","message"],"additionalProperties":false}},"requests":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limits":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"provenance":{"type":"object","properties":{"model":{"type":"null"},"apiProvider":{"type":"null"},"requestMethod":{"type":"string","const":"http"},"analysisMethod":{"type":"string","const":"static_html"},"version":{"type":"string","const":"1"},"geoFocus":{"type":"null"},"durationMs":{"type":"number","minimum":0}},"required":["model","apiProvider","requestMethod","analysisMethod","version","geoFocus","durationMs"],"additionalProperties":false}},"required":["kind","seedUrl","createdAt","confirmedAt","crawlStatus","enrichmentId","issues","requests","bytes","limits","provenance"],"additionalProperties":false},"site":{"anyOf":[{"type":"object","properties":{"crawlerAccess":{"type":"object","properties":{"url":{"type":"string"},"observedAt":{"type":"string"},"robots":{"type":"string","enum":["found","not_found","unavailable"]},"agents":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"agent":{"type":"string","enum":["GPTBot","OAI-SearchBot","ChatGPT-User","ClaudeBot","Claude-SearchBot","PerplexityBot","Google-Extended","Googlebot"]},"allowed":{"type":"boolean"}},"required":["agent","allowed"],"additionalProperties":false}},"sitemap":{"type":"string","enum":["declared","found","not_found","unavailable"]},"llmsTxt":{"type":"string","enum":["found","not_found","unavailable"]}},"required":["url","observedAt","robots","agents","sitemap","llmsTxt"],"additionalProperties":false},"entity":{"type":"object","properties":{"url":{"type":"string"},"observedAt":{"type":"string"},"status":{"type":"string","enum":["checked","unavailable"]},"incomplete":{"type":"boolean"},"organization":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","maxLength":128},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"hasUrl":{"type":"boolean"},"hasLogo":{"type":"boolean"},"sameAsCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"profiles":{"maxItems":9,"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["linkedin","x","wikipedia","wikidata","crunchbase","github","youtube","facebook","instagram"]},"url":{"type":"string","maxLength":2048}},"required":["network","url"],"additionalProperties":false}}},"required":["type","name","hasUrl","hasLogo","sameAsCount","profiles"],"additionalProperties":false},{"type":"null"}]},"brandName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},"required":["url","observedAt","status","incomplete","organization","brandName"],"additionalProperties":false},"sitemap":{"type":"object","properties":{"urlCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"complete":{"type":"boolean"}},"required":["urlCount","complete"],"additionalProperties":false},"robotsBlocked":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"examples":{"maxItems":20,"type":"array","items":{"type":"string"}}},"required":["count","examples"],"additionalProperties":false},"brokenLinks":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"linkedFrom":{"maxItems":3,"type":"array","items":{"type":"string"}}},"required":["url","linkedFrom"],"additionalProperties":false}},"pageSpeed":{"type":"object","properties":{"source":{"type":"string","const":"crux"},"formFactor":{"type":"string","const":"all"},"checkedAt":{"type":"string"},"results":{"maxItems":5,"type":"array","items":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"outcome":{"type":"string","enum":["url","origin","no_data","unavailable"]},"period":{"anyOf":[{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}},"required":["first","last"],"additionalProperties":false},{"type":"null"}]},"lcpMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"inpMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"cls":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","outcome","period","lcpMs","inpMs","cls"],"additionalProperties":false}}},"required":["source","formFactor","checkedAt","results"],"additionalProperties":false},"sourceOrigin":{"type":"object","properties":{"requestedUrl":{"type":"string"},"canonicalUrl":{"type":"string"}},"required":["requestedUrl","canonicalUrl"],"additionalProperties":false}},"required":["crawlerAccess","entity"],"additionalProperties":false},{"type":"null"}]},"siteChecks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]},"label":{"type":"string"},"status":{"type":"string","enum":["pass","fail","unknown"]},"evidence":{"type":"string"},"action":{"type":"string"},"informational":{"type":"boolean","const":true},"url":{"type":"string"},"observedAt":{"type":"string"}},"required":["id","label","status","evidence","action","url","observedAt"],"additionalProperties":false}},"limitations":{"type":"array","items":{"type":"string"}}},"required":["id","projectId","status","checkVersion","counts","pages","source","siteChecks","limitations"],"additionalProperties":false}},"required":["audit"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/site-audit":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Read the daily site check settings","description":"Read whether the daily site check is on (default), when it last ran and when the next is due. Free; no provider call and no answer units.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Daily site check settings","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"settings":{"type":"object","properties":{"auto":{"type":"boolean"},"schedule":{"type":"string","enum":["off","no_domain","scheduled"]},"lastCheckedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextCheckAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"latestAuditId":{"anyOf":[{"type":"string"},{"type":"null"}]},"seenAuditId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["auto","schedule","lastCheckedAt","nextCheckAt","latestAuditId","seenAuditId"],"additionalProperties":false}},"required":["settings"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Turn the daily site check on or off, or mark the latest audit as seen","description":"Turn the daily site check on or off (auto) and/or mark the latest audit run as seen (seenAuditId). Free: no provider call and no answer units. Retry with the same key.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"auto":{"type":"boolean"},"seenAuditId":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false}}}},"responses":{"200":{"description":"Daily site check settings","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"settings":{"type":"object","properties":{"auto":{"type":"boolean"},"schedule":{"type":"string","enum":["off","no_domain","scheduled"]},"lastCheckedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"nextCheckAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"latestAuditId":{"anyOf":[{"type":"string"},{"type":"null"}]},"seenAuditId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["auto","schedule","lastCheckedAt","nextCheckAt","latestAuditId","seenAuditId"],"additionalProperties":false}},"required":["settings"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/audits/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Read up to ten audits; unrelated or unavailable ids return null","description":"Read-only derivation from immutable stored crawl evidence. No network collection or provider spend.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"auditIds":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["auditIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Captured audit evidence","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"audits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"audit":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"status":{"type":"string","enum":["available","partial","evidence_unavailable"]},"checkVersion":{"type":"string","enum":["1","2","3","4"]},"counts":{"type":"object","properties":{"pass":{"type":"integer","minimum":0,"maximum":9007199254740991},"fail":{"type":"integer","minimum":0,"maximum":9007199254740991},"unknown":{"type":"integer","minimum":0,"maximum":9007199254740991},"run":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["pass","fail","unknown","run"],"additionalProperties":false},"pages":{"type":"array","items":{"type":"object","properties":{"source":{"type":"object","properties":{"receipt":{"type":"object","properties":{"requestedUrl":{"type":"string"},"url":{"type":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"contentType":{"type":"string"},"sha256":{"type":"string"},"fetchedAt":{"type":"string"}},"required":["requestedUrl","url","status","contentType","sha256","fetchedAt"],"additionalProperties":false},"kind":{"type":"string","enum":["static_html","challenge","rate_limited","javascript_shell","unclassified"]},"title":{"type":"object","properties":{"value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"truncated":{"type":"boolean"}},"required":["value","truncated"],"additionalProperties":false},"description":{"type":"object","properties":{"value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"truncated":{"type":"boolean"}},"required":["value","truncated"],"additionalProperties":false},"canonical":{"type":"object","properties":{"declared":{"type":"object","properties":{"value":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"truncated":{"type":"boolean"}},"required":["value","truncated"],"additionalProperties":false},"resolved":{"anyOf":[{"type":"string"},{"type":"null"}]},"count":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["declared","resolved","count"],"additionalProperties":false},"robotsMeta":{"type":"object","properties":{"entries":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"agent":{"type":"string"},"content":{"type":"string"}},"required":["agent","content"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["entries","truncated"],"additionalProperties":false},"robotsHeader":{"type":"object","properties":{"captured":{"type":"boolean"},"values":{"maxItems":20,"type":"array","items":{"type":"string"}},"truncated":{"type":"boolean"}},"required":["captured","values","truncated"],"additionalProperties":false},"headings":{"type":"object","properties":{"entries":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"level":{"type":"integer","minimum":1,"maximum":6},"text":{"type":"string"}},"required":["level","text"],"additionalProperties":false}},"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"h1Count":{"type":"integer","minimum":0,"maximum":9007199254740991},"truncated":{"type":"boolean"}},"required":["entries","count","h1Count","truncated"],"additionalProperties":false},"internalLinks":{"type":"object","properties":{"entries":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"text":{"type":"string"},"rel":{"type":"string"}},"required":["url","text","rel"],"additionalProperties":false}},"truncated":{"type":"boolean"}},"required":["entries","truncated"],"additionalProperties":false},"textCapture":{"type":"object","properties":{"version":{"type":"string","const":"1"},"status":{"type":"string","enum":["available","partial","unavailable"]},"blocks":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tag":{"type":"string","enum":["h1","h2","h3","h4","h5","h6","p","li"]},"text":{"type":"string"},"hash":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["id","tag","text","hash"],"additionalProperties":false}},"bytes":{"type":"integer","minimum":0,"maximum":16384},"hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"reason":{"anyOf":[{"type":"string","enum":["limited","no_text","capacity"]},{"type":"null"}]}},"required":["version","status","blocks","bytes","hash","reason"],"additionalProperties":false},"jsonLd":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"inspected":{"type":"integer","minimum":0,"maximum":9007199254740991},"scripts":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"status":{"type":"string","enum":["valid_json","invalid_json","external","too_large","budget_exhausted"]},"sha256":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}]}},"required":["status","sha256"],"additionalProperties":false}},"types":{"maxItems":32,"type":"array","items":{"type":"string"}},"incomplete":{"type":"boolean"}},"required":["count","inspected","scripts","types","incomplete"],"additionalProperties":false},"signals":{"type":"object","properties":{"content":{"type":"object","properties":{"wordCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"textHash":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["wordCount","textHash"],"additionalProperties":false},"images":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"missingAlt":{"type":"integer","minimum":0,"maximum":9007199254740991},"examples":{"maxItems":3,"type":"array","items":{"type":"string"}}},"required":["total","missingAlt","examples"],"additionalProperties":false},"viewport":{"type":"boolean"},"mixedContent":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"active":{"type":"integer","minimum":0,"maximum":9007199254740991},"examples":{"maxItems":3,"type":"array","items":{"type":"string"}}},"required":["count","active","examples"],"additionalProperties":false},"dates":{"type":"object","properties":{"published":{"anyOf":[{"type":"string"},{"type":"null"}]},"modified":{"anyOf":[{"type":"string"},{"type":"null"}]},"timeElement":{"type":"boolean"}},"required":["published","modified","timeElement"],"additionalProperties":false},"noSnippetAttribute":{"type":"integer","minimum":0,"maximum":9007199254740991},"social":{"type":"object","properties":{"ogImage":{"anyOf":[{"type":"string"},{"type":"null"}]},"ogTitle":{"type":"boolean"},"ogDescription":{"type":"boolean"}},"required":["ogImage","ogTitle","ogDescription"],"additionalProperties":false},"linkedFrom":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"pages":{"maxItems":5,"type":"array","items":{"type":"string"}}},"required":["count","pages"],"additionalProperties":false}},"required":["content","images","viewport","dates","noSnippetAttribute","social","linkedFrom"],"additionalProperties":false}},"required":["receipt","kind","title","description","canonical","robotsMeta","robotsHeader","headings","internalLinks"],"additionalProperties":false},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]},"label":{"type":"string"},"status":{"type":"string","enum":["pass","fail","unknown"]},"evidence":{"type":"string"},"action":{"type":"string"},"informational":{"type":"boolean","const":true}},"required":["id","label","status","evidence","action"],"additionalProperties":false}}},"required":["source","checks"],"additionalProperties":false}},"source":{"type":"object","properties":{"kind":{"type":"string","enum":["confirmed_enrichment","audit_run"]},"seedUrl":{"type":"string","format":"uri"},"createdAt":{"type":"string"},"confirmedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"crawlStatus":{"type":"string","enum":["complete","partial","blocked"]},"enrichmentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"issues":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"targetUrl":{"type":"string","format":"uri"}},"required":["url","code","message"],"additionalProperties":false}},"requests":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limits":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"provenance":{"type":"object","properties":{"model":{"type":"null"},"apiProvider":{"type":"null"},"requestMethod":{"type":"string","const":"http"},"analysisMethod":{"type":"string","const":"static_html"},"version":{"type":"string","const":"1"},"geoFocus":{"type":"null"},"durationMs":{"type":"number","minimum":0}},"required":["model","apiProvider","requestMethod","analysisMethod","version","geoFocus","durationMs"],"additionalProperties":false}},"required":["kind","seedUrl","createdAt","confirmedAt","crawlStatus","enrichmentId","issues","requests","bytes","limits","provenance"],"additionalProperties":false},"site":{"anyOf":[{"type":"object","properties":{"crawlerAccess":{"type":"object","properties":{"url":{"type":"string"},"observedAt":{"type":"string"},"robots":{"type":"string","enum":["found","not_found","unavailable"]},"agents":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"agent":{"type":"string","enum":["GPTBot","OAI-SearchBot","ChatGPT-User","ClaudeBot","Claude-SearchBot","PerplexityBot","Google-Extended","Googlebot"]},"allowed":{"type":"boolean"}},"required":["agent","allowed"],"additionalProperties":false}},"sitemap":{"type":"string","enum":["declared","found","not_found","unavailable"]},"llmsTxt":{"type":"string","enum":["found","not_found","unavailable"]}},"required":["url","observedAt","robots","agents","sitemap","llmsTxt"],"additionalProperties":false},"entity":{"type":"object","properties":{"url":{"type":"string"},"observedAt":{"type":"string"},"status":{"type":"string","enum":["checked","unavailable"]},"incomplete":{"type":"boolean"},"organization":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","maxLength":128},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"hasUrl":{"type":"boolean"},"hasLogo":{"type":"boolean"},"sameAsCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"profiles":{"maxItems":9,"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["linkedin","x","wikipedia","wikidata","crunchbase","github","youtube","facebook","instagram"]},"url":{"type":"string","maxLength":2048}},"required":["network","url"],"additionalProperties":false}}},"required":["type","name","hasUrl","hasLogo","sameAsCount","profiles"],"additionalProperties":false},{"type":"null"}]},"brandName":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},"required":["url","observedAt","status","incomplete","organization","brandName"],"additionalProperties":false},"sitemap":{"type":"object","properties":{"urlCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"complete":{"type":"boolean"}},"required":["urlCount","complete"],"additionalProperties":false},"robotsBlocked":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"examples":{"maxItems":20,"type":"array","items":{"type":"string"}}},"required":["count","examples"],"additionalProperties":false},"brokenLinks":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"linkedFrom":{"maxItems":3,"type":"array","items":{"type":"string"}}},"required":["url","linkedFrom"],"additionalProperties":false}},"pageSpeed":{"type":"object","properties":{"source":{"type":"string","const":"crux"},"formFactor":{"type":"string","const":"all"},"checkedAt":{"type":"string"},"results":{"maxItems":5,"type":"array","items":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"outcome":{"type":"string","enum":["url","origin","no_data","unavailable"]},"period":{"anyOf":[{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}},"required":["first","last"],"additionalProperties":false},{"type":"null"}]},"lcpMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"inpMs":{"anyOf":[{"type":"number"},{"type":"null"}]},"cls":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["url","outcome","period","lcpMs","inpMs","cls"],"additionalProperties":false}}},"required":["source","formFactor","checkedAt","results"],"additionalProperties":false},"sourceOrigin":{"type":"object","properties":{"requestedUrl":{"type":"string"},"canonicalUrl":{"type":"string"}},"required":["requestedUrl","canonicalUrl"],"additionalProperties":false}},"required":["crawlerAccess","entity"],"additionalProperties":false},{"type":"null"}]},"siteChecks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]},"label":{"type":"string"},"status":{"type":"string","enum":["pass","fail","unknown"]},"evidence":{"type":"string"},"action":{"type":"string"},"informational":{"type":"boolean","const":true},"url":{"type":"string"},"observedAt":{"type":"string"}},"required":["id","label","status","evidence","action","url","observedAt"],"additionalProperties":false}},"limitations":{"type":"array","items":{"type":"string"}}},"required":["id","projectId","status","checkVersion","counts","pages","source","siteChecks","limitations"],"additionalProperties":false},{"type":"null"}]}},"required":["id","audit"],"additionalProperties":false}}},"required":["audits"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/opportunities":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"List prioritised site-audit opportunities for a project","description":"Read-only derivation from the latest saved site audit. Priority and effort are fixed per check type, not a measured impact. Each item carries a group (technical, content or ai_readiness), an ai flag, a neutral why, a fixPrompt and an isNew flag, and the result carries a comparison with the previous audit. AI training crawlers and llms.txt are informational and never listed. No crawl, provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"auditId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Opportunities grouped by problem","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"audit":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"seedUrl":{"type":"string"},"createdAt":{"type":"string"},"status":{"type":"string","enum":["available","partial","evidence_unavailable"]},"pages":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","seedUrl","createdAt","status","pages"],"additionalProperties":false},{"type":"null"}]},"opportunities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]},"title":{"type":"string"},"category":{"type":"string","enum":["retrieval","structure","schema","crawler_access","entity"]},"group":{"type":"string","enum":["technical","content","ai_readiness"]},"ai":{"type":"boolean"},"why":{"type":"string"},"scope":{"type":"string","enum":["page","site"]},"priority":{"type":"string","enum":["high","medium","low"]},"effort":{"type":"string","enum":["quick","moderate","larger"]},"fix":{"type":"string"},"fixPrompt":{"type":"string"},"isNew":{"type":"boolean"},"markedDone":{"type":"boolean"},"stillFound":{"type":"boolean"},"evidence":{"anyOf":[{"type":"string"},{"type":"null"}]},"pageCount":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"evidence":{"type":"string"},"observedAt":{"type":"string"}},"required":["url","evidence","observedAt"],"additionalProperties":false}}},"required":["id","title","category","group","ai","why","scope","priority","effort","fix","fixPrompt","isNew","markedDone","stillFound","evidence","pageCount","pages"],"additionalProperties":false}},"notVerifiedPages":{"type":"integer","minimum":0,"maximum":9007199254740991},"comparison":{"anyOf":[{"type":"object","properties":{"previousAuditId":{"type":"string"},"previousCreatedAt":{"type":"string"},"newCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"resolvedCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"comparablePages":{"type":"integer","minimum":0,"maximum":9007199254740991},"firstCheckedCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["previousAuditId","previousCreatedAt","newCount","resolvedCount","comparablePages","firstCheckedCount"],"additionalProperties":false},{"type":"null"}]}},"required":["audit","opportunities","notVerifiedPages","comparison"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/opportunities/batch":{"post":{"summary":"List opportunities for up to 20 projects","description":"Read-only derivation from the latest saved site audit. Priority and effort are fixed per check type, not a measured impact. Each item carries a group (technical, content or ai_readiness), an ai flag, a neutral why, a fixPrompt and an isNew flag, and the result carries a comparison with the previous audit. AI training crawlers and llms.txt are informational and never listed. No crawl, provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"projectIds":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["projectIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Opportunities grouped by problem","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"audit":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"seedUrl":{"type":"string"},"createdAt":{"type":"string"},"status":{"type":"string","enum":["available","partial","evidence_unavailable"]},"pages":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","seedUrl","createdAt","status","pages"],"additionalProperties":false},{"type":"null"}]},"opportunities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]},"title":{"type":"string"},"category":{"type":"string","enum":["retrieval","structure","schema","crawler_access","entity"]},"group":{"type":"string","enum":["technical","content","ai_readiness"]},"ai":{"type":"boolean"},"why":{"type":"string"},"scope":{"type":"string","enum":["page","site"]},"priority":{"type":"string","enum":["high","medium","low"]},"effort":{"type":"string","enum":["quick","moderate","larger"]},"fix":{"type":"string"},"fixPrompt":{"type":"string"},"isNew":{"type":"boolean"},"markedDone":{"type":"boolean"},"stillFound":{"type":"boolean"},"evidence":{"anyOf":[{"type":"string"},{"type":"null"}]},"pageCount":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"evidence":{"type":"string"},"observedAt":{"type":"string"}},"required":["url","evidence","observedAt"],"additionalProperties":false}}},"required":["id","title","category","group","ai","why","scope","priority","effort","fix","fixPrompt","isNew","markedDone","stillFound","evidence","pageCount","pages"],"additionalProperties":false}},"notVerifiedPages":{"type":"integer","minimum":0,"maximum":9007199254740991},"comparison":{"anyOf":[{"type":"object","properties":{"previousAuditId":{"type":"string"},"previousCreatedAt":{"type":"string"},"newCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"resolvedCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"comparablePages":{"type":"integer","minimum":0,"maximum":9007199254740991},"firstCheckedCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["previousAuditId","previousCreatedAt","newCount","resolvedCount","comparablePages","firstCheckedCount"],"additionalProperties":false},{"type":"null"}]},"projectId":{"type":"string"}},"required":["audit","opportunities","notVerifiedPages","comparison","projectId"],"additionalProperties":false}}},"required":["projects"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/issue-marks":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"List issues the user marked done","description":"A mark is the user's claim that an issue is fixed, recorded against the audit it was made on; the next audit verifies it. No crawl, provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[],"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"marks":{"type":"array","items":{"type":"object","properties":{"checkId":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]},"auditId":{"type":"string","minLength":1,"maxLength":200},"markedBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"markedAt":{"type":"string"}},"required":["checkId","auditId","markedBy","markedAt"],"additionalProperties":false}}},"required":["marks"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"put":{"summary":"Mark one issue done","description":"A mark is the user's claim that an issue is fixed, recorded against the audit it was made on; the next audit verifies it. No crawl, provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"checkId":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]},"auditId":{"type":"string","minLength":1,"maxLength":200}},"required":["checkId","auditId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"mark":{"type":"object","properties":{"checkId":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]},"auditId":{"type":"string","minLength":1,"maxLength":200},"markedBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"markedAt":{"type":"string"}},"required":["checkId","auditId","markedBy","markedAt"],"additionalProperties":false}},"required":["mark"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/issue-marks/{checkId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"checkId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"delete":{"summary":"Remove an issue's done mark","description":"A mark is the user's claim that an issue is fixed, recorded against the audit it was made on; the next audit verifies it. No crawl, provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"checkId":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]},"removed":{"type":"boolean"}},"required":["checkId","removed"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/issue-marks/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Mark and unmark several issues in one call","description":"A mark is the user's claim that an issue is fixed, recorded against the audit it was made on; the next audit verifies it. No crawl, provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"auditId":{"type":"string","minLength":1,"maxLength":200},"mark":{"default":[],"maxItems":39,"type":"array","items":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]}},"unmark":{"default":[],"maxItems":39,"type":"array","items":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"marked":{"type":"array","items":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]}},"unmarked":{"type":"array","items":{"type":"string","enum":["indexing_directives","broken_internal_pages","redirect_chain","canonical","canonical_points_elsewhere","sitemap","sitemap_unreadable","googlebot_blocked","jsonld_syntax","internal_links","title","title_length_or_vague","title_duplicate","description","description_length","description_duplicate","main_heading","h1_multiple","generic_anchor_text","images_missing_alt","thin_content","duplicate_page_text","missing_publish_date","mixed_content","viewport_missing","robots_blocks_pages","page_speed_lcp","page_speed_inp","page_speed_cls","ai_search_crawler_access","snippets_restricted","content_not_in_html","entity_organization","entity_organization_fields","entity_same_as","entity_name_match","brand_not_in_homepage_title","ai_training_crawler_access","llms_txt"]}},"removedCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["marked","unmarked","removedCount"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/exchange":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Read exchange membership, balance and terms","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[],"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"member":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","left"]},"consentVersion":{"type":"string"},"joinedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"leftAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","status","consentVersion","joinedAt","leftAt"],"additionalProperties":false},{"type":"null"}]},"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ledger":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["starter_grant","host_verified","receive","reversal","refund"]},"amount":{"anyOf":[{"type":"number","const":1},{"type":"number","const":-1}]},"reference":{"type":"string"},"partner":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["kind","amount","reference","partner","createdAt"],"additionalProperties":false}},"terms":{"type":"object","properties":{"version":{"type":"string"},"points":{"type":"array","items":{"type":"string"}}},"required":["version","points"],"additionalProperties":false}},"required":["member","balance","ledger","terms"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/exchange/join":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Join the exchange","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"consentVersion":{"type":"string","minLength":1,"maxLength":40}},"required":["consentVersion"],"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"member":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","left"]},"consentVersion":{"type":"string"},"joinedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"leftAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","status","consentVersion","joinedAt","leftAt"],"additionalProperties":false},{"type":"null"}]},"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ledger":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["starter_grant","host_verified","receive","reversal","refund"]},"amount":{"anyOf":[{"type":"number","const":1},{"type":"number","const":-1}]},"reference":{"type":"string"},"partner":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["kind","amount","reference","partner","createdAt"],"additionalProperties":false}},"terms":{"type":"object","properties":{"version":{"type":"string"},"points":{"type":"array","items":{"type":"string"}}},"required":["version","points"],"additionalProperties":false}},"required":["member","balance","ledger","terms"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/exchange/leave":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Leave the exchange","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"member":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","left"]},"consentVersion":{"type":"string"},"joinedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"leftAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","status","consentVersion","joinedAt","leftAt"],"additionalProperties":false},{"type":"null"}]},"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ledger":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["starter_grant","host_verified","receive","reversal","refund"]},"amount":{"anyOf":[{"type":"number","const":1},{"type":"number","const":-1}]},"reference":{"type":"string"},"partner":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["kind","amount","reference","partner","createdAt"],"additionalProperties":false}},"terms":{"type":"object","properties":{"version":{"type":"string"},"points":{"type":"array","items":{"type":"string"}}},"required":["version","points"],"additionalProperties":false}},"required":["member","balance","ledger","terms"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/exchange/matches":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"List ranked exchange candidates and the activation state","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[],"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"active":{"type":"boolean"},"requiredMembers":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"requiredSharedSources":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"eligibleMembers":{"type":"integer","minimum":0,"maximum":9007199254740991},"relatedMembers":{"type":"integer","minimum":0,"maximum":9007199254740991},"windowDays":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"matches":{"type":"array","items":{"type":"object","properties":{"memberId":{"type":"string"},"domain":{"type":"string"},"sharedSources":{"type":"array","items":{"type":"string"}},"citedAnswers":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["memberId","domain","sharedSources","citedAnswers"],"additionalProperties":false}}},"required":["active","requiredMembers","requiredSharedSources","eligibleMembers","relatedMembers","windowDays","matches"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/exchange/batch":{"post":{"summary":"Read exchange state for up to 20 projects","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"projectIds":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["projectIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"member":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","left"]},"consentVersion":{"type":"string"},"joinedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"leftAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","status","consentVersion","joinedAt","leftAt"],"additionalProperties":false},{"type":"null"}]},"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ledger":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["starter_grant","host_verified","receive","reversal","refund"]},"amount":{"anyOf":[{"type":"number","const":1},{"type":"number","const":-1}]},"reference":{"type":"string"},"partner":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["kind","amount","reference","partner","createdAt"],"additionalProperties":false}},"terms":{"type":"object","properties":{"version":{"type":"string"},"points":{"type":"array","items":{"type":"string"}}},"required":["version","points"],"additionalProperties":false},"projectId":{"type":"string"}},"required":["member","balance","ledger","terms","projectId"],"additionalProperties":false}}},"required":["projects"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/exchange/matches/batch":{"post":{"summary":"Read exchange matching for up to 20 projects","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"projectIds":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["projectIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"projectId":{"type":"string"},"matching":{"anyOf":[{"type":"object","properties":{"active":{"type":"boolean"},"requiredMembers":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"requiredSharedSources":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"eligibleMembers":{"type":"integer","minimum":0,"maximum":9007199254740991},"relatedMembers":{"type":"integer","minimum":0,"maximum":9007199254740991},"windowDays":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"matches":{"type":"array","items":{"type":"object","properties":{"memberId":{"type":"string"},"domain":{"type":"string"},"sharedSources":{"type":"array","items":{"type":"string"}},"citedAnswers":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["memberId","domain","sharedSources","citedAnswers"],"additionalProperties":false}}},"required":["active","requiredMembers","requiredSharedSources","eligibleMembers","relatedMembers","windowDays","matches"],"additionalProperties":false},{"type":"null"}]}},"required":["projectId","matching"],"additionalProperties":false}}},"required":["projects"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/exchange/placements":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Read toApprove, hosting and receiving placements with balance and held credits","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[],"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"held":{"type":"integer","minimum":0,"maximum":9007199254740991},"available":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"counts":{"type":"object","properties":{"toApprove":{"type":"integer","minimum":0,"maximum":9007199254740991},"hosting":{"type":"integer","minimum":0,"maximum":9007199254740991},"receiving":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["toApprove","hosting","receiving"],"additionalProperties":false},"toApprove":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false}},"hosting":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false}},"receiving":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false}}},"required":["balance","held","available","counts","toApprove","hosting","receiving"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Request a link from a matched member (holds 1 credit)","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"hostMemberId":{"type":"string","minLength":1,"maxLength":200},"targetUrl":{"type":"string","minLength":1,"maxLength":2048},"anchorText":{"type":"string","minLength":1,"maxLength":200}},"required":["hostMemberId","targetUrl","anchorText"],"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"placement":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false}},"required":["placement"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/exchange/placements/{placementId}/cancel":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"placementId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Withdraw a link request before it is approved","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"placement":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false}},"required":["placement"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/exchange/placements/{placementId}/document":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"placementId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Host: choose the Content document that will carry the link","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"documentId":{"type":"string","minLength":1,"maxLength":200}},"required":["documentId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"placement":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false}},"required":["placement"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/exchange/placements/{placementId}/edit":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"placementId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Host: edit the suggested sentence or link text","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"sentence":{"type":"string","minLength":1,"maxLength":400},"anchorText":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"placement":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false}},"required":["placement"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/exchange/placements/{placementId}/approve":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"placementId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Host: approve the suggested change and add the sentence to the document draft","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"placement":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false}},"required":["placement"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/exchange/placements/{placementId}/decline":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"placementId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Host: decline a request (free)","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"placement":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false}},"required":["placement"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/exchange/placements/{placementId}/verify":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"placementId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Host: fetch the published page and verify the link","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"publishedUrl":{"type":"string","minLength":1,"maxLength":2048}},"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"placement":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false}},"required":["placement"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/exchange/placements/decide":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Host: approve or decline up to 20 requests","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"decisions":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"placementId":{"type":"string","minLength":1,"maxLength":200},"action":{"type":"string","enum":["approve","decline"]}},"required":["placementId","action"],"additionalProperties":false}}},"required":["decisions"],"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"placementId":{"type":"string"},"placement":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["placementId","placement","error"],"additionalProperties":false}}},"required":["results"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/exchange/placements/verify":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Host: verify up to 10 published links","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"placementIds":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["placementIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"placementId":{"type":"string"},"placement":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["placementId","placement","error"],"additionalProperties":false}}},"required":["results"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/exchange/placements/batch":{"post":{"summary":"Read exchange placements for up to 20 projects","description":"Link-exchange membership is per project. Credits are one-for-one and derive from an append-only ledger; matching uses websites AI engines cite (cited links only, not retrieved pages) in answers to both members' tracked questions over windowDays, excludes both members' own domains and competitors either tracks, and stays empty until enough relevant members exist. Placements are host-approved links: a request holds 1 credit, spent only when the host's published page is verified with rel=\"sponsored nofollow\" and a visible Partner link label. No provider calls or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"projectIds":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["projectIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"held":{"type":"integer","minimum":0,"maximum":9007199254740991},"available":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"counts":{"type":"object","properties":{"toApprove":{"type":"integer","minimum":0,"maximum":9007199254740991},"hosting":{"type":"integer","minimum":0,"maximum":9007199254740991},"receiving":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["toApprove","hosting","receiving"],"additionalProperties":false},"toApprove":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false}},"hosting":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false}},"receiving":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["host","receiver"]},"status":{"type":"string","enum":["requested","drafted","approved","live","removed","label_changed","reversed","declined","cancelled","expired"]},"partnerDomain":{"type":"string"},"targetUrl":{"type":"string"},"anchorText":{"type":"string"},"sentence":{"anyOf":[{"type":"string"},{"type":"null"}]},"sharedSources":{"type":"array","items":{"type":"string"}},"document":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false},{"type":"null"}]},"publishedUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheck":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckDetail":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"proofId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","role","status","partnerDomain","targetUrl","anchorText","sentence","sharedSources","document","publishedUrl","lastCheck","lastCheckDetail","lastCheckedAt","graceEndsAt","proofId","requestedAt","updatedAt"],"additionalProperties":false}},"projectId":{"type":"string"}},"required":["balance","held","available","counts","toApprove","hosting","receiving","projectId"],"additionalProperties":false}}},"required":["projects"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/recommendations":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"List recommendations for a project","description":"Recommendations are derived from data already saved for the project; priority is a fixed tier per kind, not a measured impact. A mark is the user's claim, never a verification. No crawl, scan, provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","done","declined"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"recommendations":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["setup","question_quality","content_gap"]},"category":{"type":"string","enum":["setup","questions","content"]},"priority":{"type":"string","enum":["critical","high","medium"]},"title":{"type":"string"},"summary":{"type":"string"},"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"foundAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"steps":{"maxItems":3,"type":"array","items":{"type":"string"}},"evidence":{"maxItems":5,"type":"array","items":{"type":"object","properties":{"runId":{"type":"string"},"engine":{"type":"string"},"observedAt":{"type":"string"},"competitors":{"type":"array","items":{"type":"string"}},"href":{"type":"string"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["runId","engine","observedAt","competitors","href","excerpt"],"additionalProperties":false}},"evidenceCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"sources":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"kind":{"type":"string","enum":["cited","retrieved"]},"isYours":{"type":"boolean"},"runs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["domain","kind","isYours","runs"],"additionalProperties":false}},"suggestions":{"maxItems":5,"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"answers":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["name","answers"],"additionalProperties":false}},"results":{"anyOf":[{"type":"object","properties":{"named":{"type":"integer","minimum":0,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["named","total"],"additionalProperties":false},{"type":"null"}]},"action":{"type":"object","properties":{"label":{"type":"string"},"href":{"type":"string"}},"required":["label","href"],"additionalProperties":false},"state":{"type":"string","enum":["open","done","declined"]},"markedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"markedBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"stillFound":{"type":"boolean"}},"required":["key","kind","category","priority","title","summary","question","foundAt","steps","evidence","evidenceCount","sources","suggestions","results","action","state","markedAt","markedBy","stillFound"],"additionalProperties":false}},"counts":{"type":"object","properties":{"open":{"type":"integer","minimum":0,"maximum":9007199254740991},"done":{"type":"integer","minimum":0,"maximum":9007199254740991},"declined":{"type":"integer","minimum":0,"maximum":9007199254740991},"byCategory":{"type":"object","properties":{"setup":{"type":"integer","minimum":0,"maximum":9007199254740991},"questions":{"type":"integer","minimum":0,"maximum":9007199254740991},"content":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["setup","questions","content"],"additionalProperties":false}},"required":["open","done","declined","byCategory"],"additionalProperties":false},"totals":{"type":"object","properties":{"questions":{"type":"integer","minimum":0,"maximum":9007199254740991},"gaps":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["questions","gaps"],"additionalProperties":false}},"required":["recommendations","counts","totals"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/recommendations/batch":{"post":{"summary":"List recommendations for up to 20 projects","description":"Recommendations are derived from data already saved for the project; priority is a fixed tier per kind, not a measured impact. A mark is the user's claim, never a verification. No crawl, scan, provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"projectIds":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["projectIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"recommendations":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["setup","question_quality","content_gap"]},"category":{"type":"string","enum":["setup","questions","content"]},"priority":{"type":"string","enum":["critical","high","medium"]},"title":{"type":"string"},"summary":{"type":"string"},"question":{"anyOf":[{"type":"string"},{"type":"null"}]},"foundAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"steps":{"maxItems":3,"type":"array","items":{"type":"string"}},"evidence":{"maxItems":5,"type":"array","items":{"type":"object","properties":{"runId":{"type":"string"},"engine":{"type":"string"},"observedAt":{"type":"string"},"competitors":{"type":"array","items":{"type":"string"}},"href":{"type":"string"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["runId","engine","observedAt","competitors","href","excerpt"],"additionalProperties":false}},"evidenceCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"sources":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"kind":{"type":"string","enum":["cited","retrieved"]},"isYours":{"type":"boolean"},"runs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["domain","kind","isYours","runs"],"additionalProperties":false}},"suggestions":{"maxItems":5,"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"answers":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["name","answers"],"additionalProperties":false}},"results":{"anyOf":[{"type":"object","properties":{"named":{"type":"integer","minimum":0,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["named","total"],"additionalProperties":false},{"type":"null"}]},"action":{"type":"object","properties":{"label":{"type":"string"},"href":{"type":"string"}},"required":["label","href"],"additionalProperties":false},"state":{"type":"string","enum":["open","done","declined"]},"markedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"markedBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"stillFound":{"type":"boolean"}},"required":["key","kind","category","priority","title","summary","question","foundAt","steps","evidence","evidenceCount","sources","suggestions","results","action","state","markedAt","markedBy","stillFound"],"additionalProperties":false}},"counts":{"type":"object","properties":{"open":{"type":"integer","minimum":0,"maximum":9007199254740991},"done":{"type":"integer","minimum":0,"maximum":9007199254740991},"declined":{"type":"integer","minimum":0,"maximum":9007199254740991},"byCategory":{"type":"object","properties":{"setup":{"type":"integer","minimum":0,"maximum":9007199254740991},"questions":{"type":"integer","minimum":0,"maximum":9007199254740991},"content":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["setup","questions","content"],"additionalProperties":false}},"required":["open","done","declined","byCategory"],"additionalProperties":false},"totals":{"type":"object","properties":{"questions":{"type":"integer","minimum":0,"maximum":9007199254740991},"gaps":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["questions","gaps"],"additionalProperties":false},"projectId":{"type":"string"}},"required":["recommendations","counts","totals","projectId"],"additionalProperties":false}}},"required":["projects"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/recommendation-marks":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"put":{"summary":"Mark a recommendation done or declined","description":"Recommendations are derived from data already saved for the project; priority is a fixed tier per kind, not a measured impact. A mark is the user's claim, never a verification. No crawl, scan, provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"key":{"type":"string","minLength":3,"maxLength":200,"pattern":"^[a-z_]+:[A-Za-z0-9_.-]+$"},"status":{"type":"string","enum":["done","declined"]}},"required":["key","status"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"mark":{"type":"object","properties":{"key":{"type":"string"},"status":{"type":"string","enum":["done","declined"]},"markedBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"markedAt":{"type":"string"}},"required":["key","status","markedBy","markedAt"],"additionalProperties":false}},"required":["mark"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/recommendation-marks/{key}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"key","in":"path","required":true,"description":"URL-encoded recommendation key, for example gap%3A<promptId>.","schema":{"type":"string","minLength":1}}],"delete":{"summary":"Remove a recommendation's mark","description":"Recommendations are derived from data already saved for the project; priority is a fixed tier per kind, not a measured impact. A mark is the user's claim, never a verification. No crawl, scan, provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"key":{"type":"string"},"removed":{"type":"boolean"}},"required":["key","removed"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/recommendation-marks/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Mark and clear several recommendations in one call","description":"Recommendations are derived from data already saved for the project; priority is a fixed tier per kind, not a measured impact. A mark is the user's claim, never a verification. No crawl, scan, provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"set":{"default":[],"maxItems":50,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":3,"maxLength":200,"pattern":"^[a-z_]+:[A-Za-z0-9_.-]+$"},"status":{"type":"string","enum":["done","declined"]}},"required":["key","status"],"additionalProperties":false}},"clear":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","minLength":3,"maxLength":200,"pattern":"^[a-z_]+:[A-Za-z0-9_.-]+$"}}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"marked":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"status":{"type":"string","enum":["done","declined"]},"markedBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"markedAt":{"type":"string"}},"required":["key","status","markedBy","markedAt"],"additionalProperties":false}},"cleared":{"type":"array","items":{"type":"string"}},"removedCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["marked","cleared","removedCount"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/site-pages":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"List a project's sitemap pages","description":"Pages listed in the project's sitemap with issue counts from the latest saved audit that read each page. A page no audit read is not_checked with null counts. Never crawls; no provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"filter","in":"query","required":false,"schema":{"type":"string","enum":["all","issues","unchecked"],"default":"all"}},{"name":"query","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"listing":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial","failed"]},"reason":{"anyOf":[{"type":"string","enum":["no_sitemap","unreadable","url_limit","file_limit","timeout"]},{"type":"null"}]},"urlCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"filesRead":{"type":"integer","minimum":0,"maximum":9007199254740991},"attemptedAt":{"type":"string"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"urlCap":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["status","reason","urlCount","filesRead","attemptedAt","updatedAt","urlCap"],"additionalProperties":false},{"type":"null"}]},"counts":{"type":"object","properties":{"all":{"type":"integer","minimum":0,"maximum":9007199254740991},"issues":{"type":"integer","minimum":0,"maximum":9007199254740991},"unchecked":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["all","issues","unchecked"],"additionalProperties":false},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"state":{"type":"string","enum":["checked","not_verified","not_checked"]},"issueCount":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"checksPassed":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"auditId":{"anyOf":[{"type":"string"},{"type":"null"}]},"issues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"severity":{"type":"string","enum":["high","medium","low"]},"group":{"type":"string","enum":["technical","content","ai_readiness"]},"fix":{"type":"string"},"why":{"type":"string"},"evidence":{"type":"string"}},"required":["id","title","severity","group","fix","why","evidence"],"additionalProperties":false}}},"required":["url","state","issueCount","checksPassed","lastCheckedAt","auditId","issues"],"additionalProperties":false}}},"required":["listing","counts","total","limit","offset","pages"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/site-pages/batch":{"post":{"summary":"List sitemap pages for up to 10 projects","description":"Pages listed in the project's sitemap with issue counts from the latest saved audit that read each page. A page no audit read is not_checked with null counts. Never crawls; no provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"filter":{"default":"all","type":"string","enum":["all","issues","unchecked"]},"query":{"type":"string","minLength":1,"maxLength":200},"limit":{"default":25,"type":"integer","minimum":1,"maximum":100},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"projectIds":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["projectIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"listing":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["complete","partial","failed"]},"reason":{"anyOf":[{"type":"string","enum":["no_sitemap","unreadable","url_limit","file_limit","timeout"]},{"type":"null"}]},"urlCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"filesRead":{"type":"integer","minimum":0,"maximum":9007199254740991},"attemptedAt":{"type":"string"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"urlCap":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["status","reason","urlCount","filesRead","attemptedAt","updatedAt","urlCap"],"additionalProperties":false},{"type":"null"}]},"counts":{"type":"object","properties":{"all":{"type":"integer","minimum":0,"maximum":9007199254740991},"issues":{"type":"integer","minimum":0,"maximum":9007199254740991},"unchecked":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["all","issues","unchecked"],"additionalProperties":false},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"state":{"type":"string","enum":["checked","not_verified","not_checked"]},"issueCount":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"checksPassed":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"lastCheckedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"auditId":{"anyOf":[{"type":"string"},{"type":"null"}]},"issues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"severity":{"type":"string","enum":["high","medium","low"]},"group":{"type":"string","enum":["technical","content","ai_readiness"]},"fix":{"type":"string"},"why":{"type":"string"},"evidence":{"type":"string"}},"required":["id","title","severity","group","fix","why","evidence"],"additionalProperties":false}}},"required":["url","state","issueCount","checksPassed","lastCheckedAt","auditId","issues"],"additionalProperties":false}},"projectId":{"type":"string"}},"required":["listing","counts","total","limit","offset","pages","projectId"],"additionalProperties":false}}},"required":["projects"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/writing-style":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Read the project's writing style","description":"Tone, words to use, words to avoid and a short note, sent with every draft, content chat and page proposal request. No provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"writingStyle":{"type":"object","properties":{"tone":{"anyOf":[{"type":"string","enum":["professional","friendly","confident","conversational","technical","playful"]},{"type":"null"}]},"use":{"type":"array","items":{"type":"string"}},"avoid":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["tone","use","avoid","notes","updatedAt"],"additionalProperties":false}},"required":["writingStyle"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"put":{"summary":"Replace the project's writing style","description":"Applies to requests made after the save. No provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"tone":{"anyOf":[{"type":"string","enum":["professional","friendly","confident","conversational","technical","playful"]},{"type":"null"}]},"use":{"maxItems":40,"type":"array","items":{"type":"string"}},"avoid":{"maxItems":40,"type":"array","items":{"type":"string"}},"notes":{"type":"string","maxLength":1000}},"required":["tone","use","avoid","notes"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"writingStyle":{"type":"object","properties":{"tone":{"anyOf":[{"type":"string","enum":["professional","friendly","confident","conversational","technical","playful"]},{"type":"null"}]},"use":{"type":"array","items":{"type":"string"}},"avoid":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["tone","use","avoid","notes","updatedAt"],"additionalProperties":false}},"required":["writingStyle"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/brand-knowledge":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"List the project's brand knowledge items","description":"Text the customer pasted, stored unedited with a source label and date added; at most 10 items of up to 20 KiB.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"sourceLabel":{"type":"string"},"text":{"type":"string"},"bytes":{"type":"integer","minimum":0,"maximum":9007199254740991},"addedAt":{"type":"string"}},"required":["id","title","sourceLabel","text","bytes","addedAt"],"additionalProperties":false}},"limits":{"type":"object","properties":{"items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"textBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","textBytes"],"additionalProperties":false}},"required":["items","limits"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Add 1 to 10 brand knowledge items","description":"Stored unedited; to change an item, delete it and add it again. A project keeps at most 10 items (409 limit_reached beyond that).","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"items":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"text":{"type":"string","minLength":1},"sourceLabel":{"default":"Pasted text","type":"string","minLength":1,"maxLength":120}},"required":["title","text"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"sourceLabel":{"type":"string"},"text":{"type":"string"},"bytes":{"type":"integer","minimum":0,"maximum":9007199254740991},"addedAt":{"type":"string"}},"required":["id","title","sourceLabel","text","bytes","addedAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/brand-knowledge/{itemId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"delete":{"summary":"Delete a brand knowledge item","description":"It is no longer sent with future requests; requests already made keep the copy saved with their input.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"deletedId":{"type":"string"}},"required":["deletedId"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/brand-knowledge/batch":{"post":{"summary":"List brand knowledge for up to 10 projects","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"projectIds":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["projectIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"sourceLabel":{"type":"string"},"text":{"type":"string"},"bytes":{"type":"integer","minimum":0,"maximum":9007199254740991},"addedAt":{"type":"string"}},"required":["id","title","sourceLabel","text","bytes","addedAt"],"additionalProperties":false}},"limits":{"type":"object","properties":{"items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"textBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","textBytes"],"additionalProperties":false},"projectId":{"type":"string"}},"required":["items","limits","projectId"],"additionalProperties":false}}},"required":["projects"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/eeat":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Read the project's E-E-A-T facts","description":"Customer-entered facts only, nothing generated or verified. No provider call or allowance use. A stale expectedUpdatedAt returns 409 conflict.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"organization":{"type":"object","properties":{"name":{"type":"string"},"legalName":{"type":"string"},"websiteUrl":{"type":"string"},"knowledgeBaseUrl":{"type":"string"},"country":{"type":"string"},"registrationNumber":{"type":"string"},"foundedYear":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"address":{"type":"string"},"socialProfiles":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["x","linkedin","facebook","instagram","youtube","tiktok","github","other"]},"url":{"type":"string"}},"required":["network","url"],"additionalProperties":false}},"logoUrl":{"type":"string"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","legalName","websiteUrl","knowledgeBaseUrl","country","registrationNumber","foundedYear","address","socialProfiles","logoUrl","updatedAt"],"additionalProperties":false},"editorial":{"type":"object","properties":{"owner":{"type":"string"},"editorInChief":{"type":"string"},"responsible":{"type":"string"},"reviewProcess":{"type":"string"},"reviewCadence":{"type":"string"},"lastPolicyReview":{"type":"string"},"team":{"type":"array","items":{"type":"string"}},"contributors":{"type":"array","items":{"type":"string"}},"policyUrl":{"type":"string"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["owner","editorInChief","responsible","reviewProcess","reviewCadence","lastPolicyReview","team","contributors","policyUrl","updatedAt"],"additionalProperties":false},"authors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"yearsOfExperience":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"bioUrl":{"type":"string"},"photoUrl":{"type":"string"},"expertise":{"type":"array","items":{"type":"string"}},"priorRoles":{"type":"array","items":{"type":"string"}},"credentials":{"type":"array","items":{"type":"string"}},"socialProfiles":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["x","linkedin","facebook","instagram","youtube","tiktok","github","other"]},"url":{"type":"string"}},"required":["network","url"],"additionalProperties":false}},"bio":{"type":"string"},"isDefault":{"type":"boolean"},"updatedAt":{"type":"string"}},"required":["id","name","role","yearsOfExperience","bioUrl","photoUrl","expertise","priorRoles","credentials","socialProfiles","bio","isDefault","updatedAt"],"additionalProperties":false}},"statements":{"type":"object","properties":{"values":{"type":"object","properties":{"experience":{"type":"object","properties":{"relationship":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["product_builder","operator","researcher","practitioner","consultant"]}]},"firstPartyData":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["yes","no"]}]},"originalResearch":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["yes","no"]}]},"handsOn":{"default":"","type":"string","maxLength":600}},"required":["relationship","firstPartyData","originalResearch","handsOn"],"additionalProperties":false},"expertise":{"type":"object","properties":{"primary":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"secondary":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"industry":{"default":"","type":"string","maxLength":160},"methodologies":{"default":[],"maxItems":4,"type":"array","items":{"type":"string","enum":["analysis","experimentation","benchmarking","aggregation"]}}},"required":["primary","secondary","industry","methodologies"],"additionalProperties":false},"authority":{"type":"object","properties":{"leadership":{"default":[],"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string"}},"required":["name","role"],"additionalProperties":false}},"customers":{"default":[],"maxItems":20,"type":"array","items":{"type":"string"}},"partnerships":{"default":[],"maxItems":20,"type":"array","items":{"type":"string"}},"research":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"media":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}}},"required":["leadership","customers","partnerships","research","media"],"additionalProperties":false},"trust":{"type":"object","properties":{"dataSources":{"default":[],"maxItems":3,"type":"array","items":{"type":"string","enum":["internal_product","aggregated_customer","public"]}},"citationPolicy":{"default":"","type":"string","maxLength":600},"factChecking":{"default":"","type":"string","maxLength":600},"conflictOfInterest":{"default":"","type":"string","maxLength":600},"security":{"default":"","type":"string","maxLength":300}},"required":["dataSources","citationPolicy","factChecking","conflictOfInterest","security"],"additionalProperties":false},"freshness":{"type":"object","properties":{"scope":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["product","industry","research","mixed"]}]},"updatePolicy":{"default":"","type":"string","maxLength":600},"triggers":{"default":[],"maxItems":4,"type":"array","items":{"type":"string","enum":["product_change","new_data","regulation","market_shift"]}},"deprecated":{"default":"","type":"string","maxLength":300}},"required":["scope","updatePolicy","triggers","deprecated"],"additionalProperties":false},"contact":{"type":"object","properties":{"editorialEmail":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":200,"pattern":"^[^\\s@<>\"',;]+@[^\\s@<>\"',;]+\\.[^\\s@<>\"',;]+$"}]},"privacyEmail":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":200,"pattern":"^[^\\s@<>\"',;]+@[^\\s@<>\"',;]+\\.[^\\s@<>\"',;]+$"}]},"accessibilityEmail":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":200,"pattern":"^[^\\s@<>\"',;]+@[^\\s@<>\"',;]+\\.[^\\s@<>\"',;]+$"}]},"feedbackProcess":{"default":"","type":"string","maxLength":600}},"required":["editorialEmail","privacyEmail","accessibilityEmail","feedbackProcess"],"additionalProperties":false},"schema":{"type":"object","properties":{"defaultAuthor":{"default":"","type":"string","maxLength":160},"defaultReviewer":{"default":"","type":"string","maxLength":160},"defaultOrganization":{"default":"","type":"string","maxLength":160},"types":{"default":[],"maxItems":7,"type":"array","items":{"type":"string","enum":["organization","person","article","faq","howto","product","dataset"]}},"effectiveDate":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}]},"lastUpdated":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}]}},"required":["defaultAuthor","defaultReviewer","defaultOrganization","types","effectiveDate","lastUpdated"],"additionalProperties":false},"optional":{"type":"object","properties":{"testimonials":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"reviews":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"citationsWhitelist":{"default":[],"maxItems":20,"type":"array","items":{"type":"string"}},"aiDisclosure":{"default":"","type":"string","maxLength":600}},"required":["testimonials","reviews","citationsWhitelist","aiDisclosure"],"additionalProperties":false}},"required":["experience","expertise","authority","trust","freshness","contact","schema","optional"],"additionalProperties":false},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["values","updatedAt"],"additionalProperties":false},"limits":{"type":"object","properties":{"profileUrls":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"authors":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"authorUrls":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"team":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"list":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["profileUrls","authors","authorUrls","team","list"],"additionalProperties":false}},"required":["organization","editorial","authors","statements","limits"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/eeat/organization":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"put":{"summary":"Replace the organisation card","description":"Customer-entered facts only, nothing generated or verified. No provider call or allowance use. A stale expectedUpdatedAt returns 409 conflict.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"default":"","type":"string","maxLength":160},"legalName":{"default":"","type":"string","maxLength":160},"websiteUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":300}]},"knowledgeBaseUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":300}]},"country":{"default":"","type":"string","maxLength":80},"registrationNumber":{"default":"","type":"string","maxLength":80},"foundedYear":{"default":null,"anyOf":[{"type":"integer","minimum":1000,"maximum":3000},{"type":"null"}]},"address":{"default":"","type":"string","maxLength":300},"socialProfiles":{"maxItems":14,"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["x","linkedin","facebook","instagram","youtube","tiktok","github","other"]},"url":{"type":"string","maxLength":300}},"required":["network","url"],"additionalProperties":false}},"logoUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":300}]},"expectedUpdatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["expectedUpdatedAt"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"organization":{"type":"object","properties":{"name":{"type":"string"},"legalName":{"type":"string"},"websiteUrl":{"type":"string"},"knowledgeBaseUrl":{"type":"string"},"country":{"type":"string"},"registrationNumber":{"type":"string"},"foundedYear":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"address":{"type":"string"},"socialProfiles":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["x","linkedin","facebook","instagram","youtube","tiktok","github","other"]},"url":{"type":"string"}},"required":["network","url"],"additionalProperties":false}},"logoUrl":{"type":"string"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","legalName","websiteUrl","knowledgeBaseUrl","country","registrationNumber","foundedYear","address","socialProfiles","logoUrl","updatedAt"],"additionalProperties":false}},"required":["organization"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/eeat/editorial":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"put":{"summary":"Replace the editorial responsibility card","description":"Customer-entered facts only, nothing generated or verified. No provider call or allowance use. A stale expectedUpdatedAt returns 409 conflict.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"owner":{"default":"","type":"string","maxLength":160},"editorInChief":{"default":"","type":"string","maxLength":160},"responsible":{"default":"","type":"string","maxLength":600},"reviewProcess":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["human","automated_human","automated"]}]},"reviewCadence":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["continuous","monthly","quarterly"]}]},"lastPolicyReview":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}]},"team":{"maxItems":40,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"contributors":{"maxItems":40,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"policyUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":300}]},"expectedUpdatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["expectedUpdatedAt"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"editorial":{"type":"object","properties":{"owner":{"type":"string"},"editorInChief":{"type":"string"},"responsible":{"type":"string"},"reviewProcess":{"type":"string"},"reviewCadence":{"type":"string"},"lastPolicyReview":{"type":"string"},"team":{"type":"array","items":{"type":"string"}},"contributors":{"type":"array","items":{"type":"string"}},"policyUrl":{"type":"string"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["owner","editorInChief","responsible","reviewProcess","reviewCadence","lastPolicyReview","team","contributors","policyUrl","updatedAt"],"additionalProperties":false}},"required":["editorial"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/eeat/statements":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"put":{"summary":"Replace the customer's own statements (E-E-A-T sections 4 to 11)","description":"Customer-entered facts only, nothing generated or verified. No provider call or allowance use. A stale expectedUpdatedAt returns 409 conflict. Every field is the customer's own unverified statement.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"experience":{"default":{},"type":"object","properties":{"relationship":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["product_builder","operator","researcher","practitioner","consultant"]}]},"firstPartyData":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["yes","no"]}]},"originalResearch":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["yes","no"]}]},"handsOn":{"default":"","type":"string","maxLength":600}},"additionalProperties":false},"expertise":{"default":{},"type":"object","properties":{"primary":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"secondary":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"industry":{"default":"","type":"string","maxLength":160},"methodologies":{"maxItems":8,"type":"array","items":{"type":"string","enum":["analysis","experimentation","benchmarking","aggregation"]}}},"additionalProperties":false},"authority":{"default":{},"type":"object","properties":{"leadership":{"maxItems":40,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"role":{"default":"","type":"string","maxLength":120}},"required":["name"],"additionalProperties":false}},"customers":{"maxItems":40,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"partnerships":{"maxItems":40,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"research":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":300}},"media":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":300}}},"additionalProperties":false},"trust":{"default":{},"type":"object","properties":{"dataSources":{"maxItems":6,"type":"array","items":{"type":"string","enum":["internal_product","aggregated_customer","public"]}},"citationPolicy":{"default":"","type":"string","maxLength":600},"factChecking":{"default":"","type":"string","maxLength":600},"conflictOfInterest":{"default":"","type":"string","maxLength":600},"security":{"default":"","type":"string","maxLength":300}},"additionalProperties":false},"freshness":{"default":{},"type":"object","properties":{"scope":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["product","industry","research","mixed"]}]},"updatePolicy":{"default":"","type":"string","maxLength":600},"triggers":{"maxItems":8,"type":"array","items":{"type":"string","enum":["product_change","new_data","regulation","market_shift"]}},"deprecated":{"default":"","type":"string","maxLength":300}},"additionalProperties":false},"contact":{"default":{},"type":"object","properties":{"editorialEmail":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":200,"pattern":"^[^\\s@<>\"',;]+@[^\\s@<>\"',;]+\\.[^\\s@<>\"',;]+$"}]},"privacyEmail":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":200,"pattern":"^[^\\s@<>\"',;]+@[^\\s@<>\"',;]+\\.[^\\s@<>\"',;]+$"}]},"accessibilityEmail":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":200,"pattern":"^[^\\s@<>\"',;]+@[^\\s@<>\"',;]+\\.[^\\s@<>\"',;]+$"}]},"feedbackProcess":{"default":"","type":"string","maxLength":600}},"additionalProperties":false},"schema":{"default":{},"type":"object","properties":{"defaultAuthor":{"default":"","type":"string","maxLength":160},"defaultReviewer":{"default":"","type":"string","maxLength":160},"defaultOrganization":{"default":"","type":"string","maxLength":160},"types":{"maxItems":14,"type":"array","items":{"type":"string","enum":["organization","person","article","faq","howto","product","dataset"]}},"effectiveDate":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}]},"lastUpdated":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}]}},"additionalProperties":false},"optional":{"default":{},"type":"object","properties":{"testimonials":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":300}},"reviews":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":300}},"citationsWhitelist":{"maxItems":40,"type":"array","items":{"type":"string","maxLength":300}},"aiDisclosure":{"default":"","type":"string","maxLength":600}},"additionalProperties":false},"expectedUpdatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["expectedUpdatedAt"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"statements":{"type":"object","properties":{"values":{"type":"object","properties":{"experience":{"type":"object","properties":{"relationship":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["product_builder","operator","researcher","practitioner","consultant"]}]},"firstPartyData":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["yes","no"]}]},"originalResearch":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["yes","no"]}]},"handsOn":{"default":"","type":"string","maxLength":600}},"required":["relationship","firstPartyData","originalResearch","handsOn"],"additionalProperties":false},"expertise":{"type":"object","properties":{"primary":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"secondary":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"industry":{"default":"","type":"string","maxLength":160},"methodologies":{"default":[],"maxItems":4,"type":"array","items":{"type":"string","enum":["analysis","experimentation","benchmarking","aggregation"]}}},"required":["primary","secondary","industry","methodologies"],"additionalProperties":false},"authority":{"type":"object","properties":{"leadership":{"default":[],"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string"}},"required":["name","role"],"additionalProperties":false}},"customers":{"default":[],"maxItems":20,"type":"array","items":{"type":"string"}},"partnerships":{"default":[],"maxItems":20,"type":"array","items":{"type":"string"}},"research":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"media":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}}},"required":["leadership","customers","partnerships","research","media"],"additionalProperties":false},"trust":{"type":"object","properties":{"dataSources":{"default":[],"maxItems":3,"type":"array","items":{"type":"string","enum":["internal_product","aggregated_customer","public"]}},"citationPolicy":{"default":"","type":"string","maxLength":600},"factChecking":{"default":"","type":"string","maxLength":600},"conflictOfInterest":{"default":"","type":"string","maxLength":600},"security":{"default":"","type":"string","maxLength":300}},"required":["dataSources","citationPolicy","factChecking","conflictOfInterest","security"],"additionalProperties":false},"freshness":{"type":"object","properties":{"scope":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["product","industry","research","mixed"]}]},"updatePolicy":{"default":"","type":"string","maxLength":600},"triggers":{"default":[],"maxItems":4,"type":"array","items":{"type":"string","enum":["product_change","new_data","regulation","market_shift"]}},"deprecated":{"default":"","type":"string","maxLength":300}},"required":["scope","updatePolicy","triggers","deprecated"],"additionalProperties":false},"contact":{"type":"object","properties":{"editorialEmail":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":200,"pattern":"^[^\\s@<>\"',;]+@[^\\s@<>\"',;]+\\.[^\\s@<>\"',;]+$"}]},"privacyEmail":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":200,"pattern":"^[^\\s@<>\"',;]+@[^\\s@<>\"',;]+\\.[^\\s@<>\"',;]+$"}]},"accessibilityEmail":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":200,"pattern":"^[^\\s@<>\"',;]+@[^\\s@<>\"',;]+\\.[^\\s@<>\"',;]+$"}]},"feedbackProcess":{"default":"","type":"string","maxLength":600}},"required":["editorialEmail","privacyEmail","accessibilityEmail","feedbackProcess"],"additionalProperties":false},"schema":{"type":"object","properties":{"defaultAuthor":{"default":"","type":"string","maxLength":160},"defaultReviewer":{"default":"","type":"string","maxLength":160},"defaultOrganization":{"default":"","type":"string","maxLength":160},"types":{"default":[],"maxItems":7,"type":"array","items":{"type":"string","enum":["organization","person","article","faq","howto","product","dataset"]}},"effectiveDate":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}]},"lastUpdated":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}]}},"required":["defaultAuthor","defaultReviewer","defaultOrganization","types","effectiveDate","lastUpdated"],"additionalProperties":false},"optional":{"type":"object","properties":{"testimonials":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"reviews":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"citationsWhitelist":{"default":[],"maxItems":20,"type":"array","items":{"type":"string"}},"aiDisclosure":{"default":"","type":"string","maxLength":600}},"required":["testimonials","reviews","citationsWhitelist","aiDisclosure"],"additionalProperties":false}},"required":["experience","expertise","authority","trust","freshness","contact","schema","optional"],"additionalProperties":false},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["values","updatedAt"],"additionalProperties":false}},"required":["statements"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/eeat/authors":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Add 1 to 20 authors","description":"Customer-entered facts only, nothing generated or verified. No provider call or allowance use. A stale expectedUpdatedAt returns 409 conflict. A project keeps at most 20 authors and at most one default (409 limit_reached beyond that).","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"authors":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"role":{"default":"","type":"string","maxLength":120},"yearsOfExperience":{"default":null,"anyOf":[{"type":"integer","minimum":0,"maximum":80},{"type":"null"}]},"bioUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":300}]},"photoUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":300}]},"expertise":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"priorRoles":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"credentials":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"socialProfiles":{"maxItems":14,"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["x","linkedin","facebook","instagram","youtube","tiktok","github","other"]},"url":{"type":"string","maxLength":300}},"required":["network","url"],"additionalProperties":false}},"bio":{"default":"","type":"string","maxLength":500},"isDefault":{"default":false,"type":"boolean"}},"required":["name"],"additionalProperties":false}}},"required":["authors"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"authors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"yearsOfExperience":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"bioUrl":{"type":"string"},"photoUrl":{"type":"string"},"expertise":{"type":"array","items":{"type":"string"}},"priorRoles":{"type":"array","items":{"type":"string"}},"credentials":{"type":"array","items":{"type":"string"}},"socialProfiles":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["x","linkedin","facebook","instagram","youtube","tiktok","github","other"]},"url":{"type":"string"}},"required":["network","url"],"additionalProperties":false}},"bio":{"type":"string"},"isDefault":{"type":"boolean"},"updatedAt":{"type":"string"}},"required":["id","name","role","yearsOfExperience","bioUrl","photoUrl","expertise","priorRoles","credentials","socialProfiles","bio","isDefault","updatedAt"],"additionalProperties":false}}},"required":["authors"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/eeat/authors/{authorId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"authorId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"put":{"summary":"Replace one author","description":"Customer-entered facts only, nothing generated or verified. No provider call or allowance use. A stale expectedUpdatedAt returns 409 conflict.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"role":{"default":"","type":"string","maxLength":120},"yearsOfExperience":{"default":null,"anyOf":[{"type":"integer","minimum":0,"maximum":80},{"type":"null"}]},"bioUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":300}]},"photoUrl":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":300}]},"expertise":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"priorRoles":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"credentials":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"socialProfiles":{"maxItems":14,"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["x","linkedin","facebook","instagram","youtube","tiktok","github","other"]},"url":{"type":"string","maxLength":300}},"required":["network","url"],"additionalProperties":false}},"bio":{"default":"","type":"string","maxLength":500},"isDefault":{"default":false,"type":"boolean"},"expectedUpdatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["name","expectedUpdatedAt"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"yearsOfExperience":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"bioUrl":{"type":"string"},"photoUrl":{"type":"string"},"expertise":{"type":"array","items":{"type":"string"}},"priorRoles":{"type":"array","items":{"type":"string"}},"credentials":{"type":"array","items":{"type":"string"}},"socialProfiles":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["x","linkedin","facebook","instagram","youtube","tiktok","github","other"]},"url":{"type":"string"}},"required":["network","url"],"additionalProperties":false}},"bio":{"type":"string"},"isDefault":{"type":"boolean"},"updatedAt":{"type":"string"}},"required":["id","name","role","yearsOfExperience","bioUrl","photoUrl","expertise","priorRoles","credentials","socialProfiles","bio","isDefault","updatedAt"],"additionalProperties":false}},"required":["author"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete one author","description":"The author is no longer sent with future requests; requests already made keep the copy saved with their input.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"deletedId":{"type":"string"}},"required":["deletedId"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/eeat/batch":{"post":{"summary":"Read E-E-A-T facts for up to 10 projects","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"projectIds":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["projectIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"organization":{"type":"object","properties":{"name":{"type":"string"},"legalName":{"type":"string"},"websiteUrl":{"type":"string"},"knowledgeBaseUrl":{"type":"string"},"country":{"type":"string"},"registrationNumber":{"type":"string"},"foundedYear":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"address":{"type":"string"},"socialProfiles":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["x","linkedin","facebook","instagram","youtube","tiktok","github","other"]},"url":{"type":"string"}},"required":["network","url"],"additionalProperties":false}},"logoUrl":{"type":"string"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","legalName","websiteUrl","knowledgeBaseUrl","country","registrationNumber","foundedYear","address","socialProfiles","logoUrl","updatedAt"],"additionalProperties":false},"editorial":{"type":"object","properties":{"owner":{"type":"string"},"editorInChief":{"type":"string"},"responsible":{"type":"string"},"reviewProcess":{"type":"string"},"reviewCadence":{"type":"string"},"lastPolicyReview":{"type":"string"},"team":{"type":"array","items":{"type":"string"}},"contributors":{"type":"array","items":{"type":"string"}},"policyUrl":{"type":"string"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["owner","editorInChief","responsible","reviewProcess","reviewCadence","lastPolicyReview","team","contributors","policyUrl","updatedAt"],"additionalProperties":false},"authors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"yearsOfExperience":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"bioUrl":{"type":"string"},"photoUrl":{"type":"string"},"expertise":{"type":"array","items":{"type":"string"}},"priorRoles":{"type":"array","items":{"type":"string"}},"credentials":{"type":"array","items":{"type":"string"}},"socialProfiles":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string","enum":["x","linkedin","facebook","instagram","youtube","tiktok","github","other"]},"url":{"type":"string"}},"required":["network","url"],"additionalProperties":false}},"bio":{"type":"string"},"isDefault":{"type":"boolean"},"updatedAt":{"type":"string"}},"required":["id","name","role","yearsOfExperience","bioUrl","photoUrl","expertise","priorRoles","credentials","socialProfiles","bio","isDefault","updatedAt"],"additionalProperties":false}},"statements":{"type":"object","properties":{"values":{"type":"object","properties":{"experience":{"type":"object","properties":{"relationship":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["product_builder","operator","researcher","practitioner","consultant"]}]},"firstPartyData":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["yes","no"]}]},"originalResearch":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["yes","no"]}]},"handsOn":{"default":"","type":"string","maxLength":600}},"required":["relationship","firstPartyData","originalResearch","handsOn"],"additionalProperties":false},"expertise":{"type":"object","properties":{"primary":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"secondary":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"industry":{"default":"","type":"string","maxLength":160},"methodologies":{"default":[],"maxItems":4,"type":"array","items":{"type":"string","enum":["analysis","experimentation","benchmarking","aggregation"]}}},"required":["primary","secondary","industry","methodologies"],"additionalProperties":false},"authority":{"type":"object","properties":{"leadership":{"default":[],"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string"}},"required":["name","role"],"additionalProperties":false}},"customers":{"default":[],"maxItems":20,"type":"array","items":{"type":"string"}},"partnerships":{"default":[],"maxItems":20,"type":"array","items":{"type":"string"}},"research":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"media":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}}},"required":["leadership","customers","partnerships","research","media"],"additionalProperties":false},"trust":{"type":"object","properties":{"dataSources":{"default":[],"maxItems":3,"type":"array","items":{"type":"string","enum":["internal_product","aggregated_customer","public"]}},"citationPolicy":{"default":"","type":"string","maxLength":600},"factChecking":{"default":"","type":"string","maxLength":600},"conflictOfInterest":{"default":"","type":"string","maxLength":600},"security":{"default":"","type":"string","maxLength":300}},"required":["dataSources","citationPolicy","factChecking","conflictOfInterest","security"],"additionalProperties":false},"freshness":{"type":"object","properties":{"scope":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","enum":["product","industry","research","mixed"]}]},"updatePolicy":{"default":"","type":"string","maxLength":600},"triggers":{"default":[],"maxItems":4,"type":"array","items":{"type":"string","enum":["product_change","new_data","regulation","market_shift"]}},"deprecated":{"default":"","type":"string","maxLength":300}},"required":["scope","updatePolicy","triggers","deprecated"],"additionalProperties":false},"contact":{"type":"object","properties":{"editorialEmail":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":200,"pattern":"^[^\\s@<>\"',;]+@[^\\s@<>\"',;]+\\.[^\\s@<>\"',;]+$"}]},"privacyEmail":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":200,"pattern":"^[^\\s@<>\"',;]+@[^\\s@<>\"',;]+\\.[^\\s@<>\"',;]+$"}]},"accessibilityEmail":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","maxLength":200,"pattern":"^[^\\s@<>\"',;]+@[^\\s@<>\"',;]+\\.[^\\s@<>\"',;]+$"}]},"feedbackProcess":{"default":"","type":"string","maxLength":600}},"required":["editorialEmail","privacyEmail","accessibilityEmail","feedbackProcess"],"additionalProperties":false},"schema":{"type":"object","properties":{"defaultAuthor":{"default":"","type":"string","maxLength":160},"defaultReviewer":{"default":"","type":"string","maxLength":160},"defaultOrganization":{"default":"","type":"string","maxLength":160},"types":{"default":[],"maxItems":7,"type":"array","items":{"type":"string","enum":["organization","person","article","faq","howto","product","dataset"]}},"effectiveDate":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}]},"lastUpdated":{"default":"","anyOf":[{"type":"string","const":""},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}]}},"required":["defaultAuthor","defaultReviewer","defaultOrganization","types","effectiveDate","lastUpdated"],"additionalProperties":false},"optional":{"type":"object","properties":{"testimonials":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"reviews":{"default":[],"maxItems":10,"type":"array","items":{"type":"string"}},"citationsWhitelist":{"default":[],"maxItems":20,"type":"array","items":{"type":"string"}},"aiDisclosure":{"default":"","type":"string","maxLength":600}},"required":["testimonials","reviews","citationsWhitelist","aiDisclosure"],"additionalProperties":false}},"required":["experience","expertise","authority","trust","freshness","contact","schema","optional"],"additionalProperties":false},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["values","updatedAt"],"additionalProperties":false},"limits":{"type":"object","properties":{"profileUrls":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"authors":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"authorUrls":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"team":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"list":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["profileUrls","authors","authorUrls","team","list"],"additionalProperties":false},"projectId":{"type":"string"}},"required":["organization","editorial","authors","statements","limits","projectId"],"additionalProperties":false}}},"required":["projects"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/source-rules":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"List the project's source rules","description":"Domains or domain paths given a source type (owned, competitor, editorial, social, forum, review, institutional, third_party or other). A path rule beats a domain rule, which beats the automatic label. Applied when sources are shown; saved citations are never changed.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"host":{"type":"string"},"path":{"type":"string"},"target":{"type":"string"},"category":{"type":"string","enum":["owned","competitor","editorial","social","forum","review","institutional","third_party","other"]},"updatedAt":{"type":"string"}},"required":["id","host","path","target","category","updatedAt"],"additionalProperties":false}},"limits":{"type":"object","properties":{"rules":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"perRequest":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["rules","perRequest"],"additionalProperties":false},"categories":{"type":"array","items":{"type":"string","enum":["owned","competitor","editorial","social","forum","review","institutional","third_party","other"]}}},"required":["rules","limits","categories"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Add 1 to 20 source rules","description":"A target that already has a rule has its category replaced. A project keeps at most 100 (409 limit_reached beyond that).","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"rules":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"target":{"type":"string","minLength":1,"maxLength":2048},"category":{"type":"string","enum":["owned","competitor","editorial","social","forum","review","institutional","third_party","other"]}},"required":["target","category"],"additionalProperties":false}}},"required":["rules"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"host":{"type":"string"},"path":{"type":"string"},"target":{"type":"string"},"category":{"type":"string","enum":["owned","competitor","editorial","social","forum","review","institutional","third_party","other"]},"updatedAt":{"type":"string"}},"required":["id","host","path","target","category","updatedAt"],"additionalProperties":false}}},"required":["rules"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/source-rules/{ruleId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"ruleId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"patch":{"summary":"Change a source rule's target or category","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"target":{"type":"string","minLength":1,"maxLength":2048},"category":{"type":"string","enum":["owned","competitor","editorial","social","forum","review","institutional","third_party","other"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"rule":{"type":"object","properties":{"id":{"type":"string"},"host":{"type":"string"},"path":{"type":"string"},"target":{"type":"string"},"category":{"type":"string","enum":["owned","competitor","editorial","social","forum","review","institutional","third_party","other"]},"updatedAt":{"type":"string"}},"required":["id","host","path","target","category","updatedAt"],"additionalProperties":false}},"required":["rule"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a source rule","description":"Sources return to the label they would have without it.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"deletedId":{"type":"string"}},"required":["deletedId"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/source-rules/impact":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Preview the impact of a rule change","description":"Counts stored citations whose label would change, with cited and retrieved kept apart. Nothing is saved.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"upsert":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200},"target":{"type":"string","minLength":1,"maxLength":2048},"category":{"type":"string","enum":["owned","competitor","editorial","social","forum","review","institutional","third_party","other"]}},"required":["target","category"],"additionalProperties":false},"removeId":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"impact":{"type":"object","properties":{"cited":{"type":"object","properties":{"changed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["changed","total"],"additionalProperties":false},"retrieved":{"type":"object","properties":{"changed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["changed","total"],"additionalProperties":false},"changes":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","enum":["owned","competitor","editorial","social","forum","review","institutional","third_party","other"]},"to":{"type":"string","enum":["owned","competitor","editorial","social","forum","review","institutional","third_party","other"]},"cited":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"retrieved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["from","to","cited","retrieved"],"additionalProperties":false}},"domains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"cited":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"retrieved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["domain","cited","retrieved"],"additionalProperties":false}}},"required":["cited","retrieved","changes","domains"],"additionalProperties":false}},"required":["impact"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/source-rules/test":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Test which source type a URL gets","description":"Returns the source type, the rule that decides it (or the automatic label) and why. Nothing is saved.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048}},"required":["url"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"result":{"type":"object","properties":{"url":{"type":"string"},"host":{"type":"string"},"path":{"type":"string"},"category":{"type":"string","enum":["owned","competitor","editorial","social","forum","review","institutional","third_party","other"]},"decidedBy":{"type":"string","enum":["path_rule","domain_rule","automatic"]},"rule":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"target":{"type":"string"},"category":{"type":"string","enum":["owned","competitor","editorial","social","forum","review","institutional","third_party","other"]},"shape":{"type":"string"}},"required":["id","target","category","shape"],"additionalProperties":false},{"type":"null"}]},"explanation":{"type":"string"},"associated":{"anyOf":[{"type":"object","properties":{"tag":{"anyOf":[{"type":"string","enum":["owned","sponsored","business_profile","pr","review","testimonial","social","owned_social","affiliate","influencer","associate_influencer","press"]},{"type":"null"}]},"scope":{"type":"string","enum":["url","domain"]},"target":{"type":"string"}},"required":["tag","scope","target"],"additionalProperties":false},{"type":"null"}]}},"required":["url","host","path","category","decidedBy","rule","explanation","associated"],"additionalProperties":false}},"required":["result"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/source-rules/batch":{"post":{"summary":"List source rules for up to 10 projects","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"projectIds":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["projectIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"host":{"type":"string"},"path":{"type":"string"},"target":{"type":"string"},"category":{"type":"string","enum":["owned","competitor","editorial","social","forum","review","institutional","third_party","other"]},"updatedAt":{"type":"string"}},"required":["id","host","path","target","category","updatedAt"],"additionalProperties":false}},"limits":{"type":"object","properties":{"rules":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"perRequest":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["rules","perRequest"],"additionalProperties":false},"categories":{"type":"array","items":{"type":"string","enum":["owned","competitor","editorial","social","forum","review","institutional","third_party","other"]}},"projectId":{"type":"string"}},"required":["rules","limits","categories","projectId"],"additionalProperties":false}}},"required":["projects"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/associated-sources":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"List associated pages and suggestions","description":"Third-party pages the customer registered (up to 10) and pages engines cited or opened in saved answers, cited and retrieved kept apart.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"host":{"type":"string"},"target":{"type":"string"},"scope":{"type":"string","enum":["url","domain"]},"tag":{"anyOf":[{"type":"string","enum":["owned","sponsored","business_profile","pr","review","testimonial","social","owned_social","affiliate","influencer","associate_influencer","press"]},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"addedAt":{"type":"string"}},"required":["id","url","host","target","scope","tag","note","addedAt"],"additionalProperties":false}},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"suggestions":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"domain":{"type":"string"},"cited":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"retrieved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"questions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["url","domain","cited","retrieved","questions"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"string","enum":["owned","sponsored","business_profile","pr","review","testimonial","social","owned_social","affiliate","influencer","associate_influencer","press"]}},"scopes":{"type":"array","items":{"type":"string","enum":["url","domain"]}}},"required":["items","limit","suggestions","tags","scopes"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Add 1 to 10 associated sources","description":"Bulk add. Each item is a page (scope url) or a domain (scope domain) with an optional tag. A project keeps at most 10 (409 limit_reached beyond that).","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"items":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"tag":{"type":"string","enum":["owned","sponsored","business_profile","pr","review","testimonial","social","owned_social","affiliate","influencer","associate_influencer","press"]},"scope":{"type":"string","enum":["url","domain"]},"note":{"type":"string","minLength":1,"maxLength":300}},"required":["url"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"host":{"type":"string"},"target":{"type":"string"},"scope":{"type":"string","enum":["url","domain"]},"tag":{"anyOf":[{"type":"string","enum":["owned","sponsored","business_profile","pr","review","testimonial","social","owned_social","affiliate","influencer","associate_influencer","press"]},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"addedAt":{"type":"string"}},"required":["id","url","host","target","scope","tag","note","addedAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/associated-sources/{itemId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"patch":{"summary":"Change an associated source's tag, scope or note","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"tag":{"anyOf":[{"type":"string","enum":["owned","sponsored","business_profile","pr","review","testimonial","social","owned_social","affiliate","influencer","associate_influencer","press"]},{"type":"null"}]},"scope":{"type":"string","enum":["url","domain"]},"note":{"anyOf":[{"type":"string","minLength":1,"maxLength":300},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"host":{"type":"string"},"target":{"type":"string"},"scope":{"type":"string","enum":["url","domain"]},"tag":{"anyOf":[{"type":"string","enum":["owned","sponsored","business_profile","pr","review","testimonial","social","owned_social","affiliate","influencer","associate_influencer","press"]},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"addedAt":{"type":"string"}},"required":["id","url","host","target","scope","tag","note","addedAt"],"additionalProperties":false}},"required":["item"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Remove an associated page","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"deletedId":{"type":"string"}},"required":["deletedId"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/associated-sources/batch":{"post":{"summary":"List associated pages for up to 10 projects","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"projectIds":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["projectIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"host":{"type":"string"},"target":{"type":"string"},"scope":{"type":"string","enum":["url","domain"]},"tag":{"anyOf":[{"type":"string","enum":["owned","sponsored","business_profile","pr","review","testimonial","social","owned_social","affiliate","influencer","associate_influencer","press"]},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"addedAt":{"type":"string"}},"required":["id","url","host","target","scope","tag","note","addedAt"],"additionalProperties":false}},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"suggestions":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"domain":{"type":"string"},"cited":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"retrieved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"questions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["url","domain","cited","retrieved","questions"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"string","enum":["owned","sponsored","business_profile","pr","review","testimonial","social","owned_social","affiliate","influencer","associate_influencer","press"]}},"scopes":{"type":"array","items":{"type":"string","enum":["url","domain"]}},"projectId":{"type":"string"}},"required":["items","limit","suggestions","tags","scopes","projectId"],"additionalProperties":false}}},"required":["projects"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/profile":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Read the confirmed business profile and topics","description":"What the customer confirmed about the business, with the current revision, where each value came from (site or edited) and each confirmed topic's count of active tracked questions. profile is null when none is confirmed. No provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"profile":{"anyOf":[{"type":"object","properties":{"enrichmentId":{"type":"string"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"confirmedAt":{"type":"string"},"example":{"type":"boolean"},"applies":{"type":"boolean"},"siteHost":{"type":"string"},"domain":{"type":"string"},"details":{"type":"object","properties":{"category":{"type":"string"},"oneLiner":{"type":"string"},"audience":{"type":"string"},"offerings":{"type":"array","items":{"type":"string"}},"useCases":{"type":"array","items":{"type":"string"}},"differentiators":{"type":"array","items":{"type":"string"}},"market":{"anyOf":[{"type":"object","properties":{"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"}},"required":["locationCode","languageCode"],"additionalProperties":false},{"type":"null"}]}},"required":["category","oneLiner","audience","offerings","useCases","differentiators","market"],"additionalProperties":false},"provenance":{"type":"object","properties":{"category":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["site","edited"]},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","at"],"additionalProperties":false},{"type":"null"}]},"oneLiner":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["site","edited"]},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","at"],"additionalProperties":false},{"type":"null"}]},"audience":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["site","edited"]},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","at"],"additionalProperties":false},{"type":"null"}]},"offerings":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["site","edited"]},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","at"],"additionalProperties":false},{"type":"null"}]},"useCases":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["site","edited"]},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","at"],"additionalProperties":false},{"type":"null"}]},"differentiators":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["site","edited"]},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","at"],"additionalProperties":false},{"type":"null"}]}},"required":["category","oneLiner","audience","offerings","useCases","differentiators"],"additionalProperties":false},"topics":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"trackedQuestions":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["text","trackedQuestions"],"additionalProperties":false}}},"required":["enrichmentId","revision","confirmedAt","example","applies","siteHost","domain","details","provenance","topics"],"additionalProperties":false},{"type":"null"}]}},"required":["profile"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Edit the confirmed business profile and/or topics","description":"Only the fields sent change. expectedRevision must match the current revision (409 revision_conflict otherwise); a save that changes nothing writes nothing. A saved change makes already-prepared drafts fail their preflight and need a fresh start. Topics replace the whole list (up to 20). No provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"details":{"type":"object","properties":{"category":{"type":"string","maxLength":2000},"oneLiner":{"type":"string","maxLength":2000},"audience":{"type":"string","maxLength":2000},"offerings":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"useCases":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"differentiators":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"market":{"anyOf":[{"type":"object","properties":{"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"}},"required":["locationCode","languageCode"],"additionalProperties":false},{"type":"null"}]}},"additionalProperties":false},"topics":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"profile":{"type":"object","properties":{"enrichmentId":{"type":"string"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"confirmedAt":{"type":"string"},"example":{"type":"boolean"},"applies":{"type":"boolean"},"siteHost":{"type":"string"},"domain":{"type":"string"},"details":{"type":"object","properties":{"category":{"type":"string"},"oneLiner":{"type":"string"},"audience":{"type":"string"},"offerings":{"type":"array","items":{"type":"string"}},"useCases":{"type":"array","items":{"type":"string"}},"differentiators":{"type":"array","items":{"type":"string"}},"market":{"anyOf":[{"type":"object","properties":{"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"}},"required":["locationCode","languageCode"],"additionalProperties":false},{"type":"null"}]}},"required":["category","oneLiner","audience","offerings","useCases","differentiators","market"],"additionalProperties":false},"provenance":{"type":"object","properties":{"category":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["site","edited"]},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","at"],"additionalProperties":false},{"type":"null"}]},"oneLiner":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["site","edited"]},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","at"],"additionalProperties":false},{"type":"null"}]},"audience":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["site","edited"]},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","at"],"additionalProperties":false},{"type":"null"}]},"offerings":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["site","edited"]},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","at"],"additionalProperties":false},{"type":"null"}]},"useCases":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["site","edited"]},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","at"],"additionalProperties":false},{"type":"null"}]},"differentiators":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["site","edited"]},"at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","at"],"additionalProperties":false},{"type":"null"}]}},"required":["category","oneLiner","audience","offerings","useCases","differentiators"],"additionalProperties":false},"topics":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"trackedQuestions":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["text","trackedQuestions"],"additionalProperties":false}}},"required":["enrichmentId","revision","confirmedAt","example","applies","siteHost","domain","details","provenance","topics"],"additionalProperties":false},"changed":{"type":"boolean"}},"required":["profile","changed"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/topics":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"List topics, active and archived","description":"Each topic with its origin (site, ai or customer), archived flag, one-line description (or null) and count of active tracked questions, plus the profile revision, the Auto-generate setting and this month's topic generations left. topics is null when no business profile is confirmed. No provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"topics":{"anyOf":[{"type":"object","properties":{"enrichmentId":{"type":"string"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"example":{"type":"boolean"},"applies":{"type":"boolean"},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"autoGenerate":{"type":"boolean"},"topics":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"origin":{"type":"string","enum":["site","ai","customer"]},"archived":{"type":"boolean"},"trackedQuestions":{"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["text","origin","archived","trackedQuestions","description"],"additionalProperties":false}},"generation":{"type":"object","properties":{"runsLimit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"runsUsed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"runsLeft":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"resetsAt":{"type":"string"},"available":{"type":"boolean"},"unavailableReason":{"anyOf":[{"type":"string","enum":["unavailable","monthly_limit","no_business_context","in_progress","plan_limit"]},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["runsLimit","runsUsed","runsLeft","resetsAt","available","unavailableReason","message"],"additionalProperties":false}},"required":["enrichmentId","revision","example","applies","limit","autoGenerate","topics","generation"],"additionalProperties":false},{"type":"null"}]}},"required":["topics"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Add, archive, restore, delete, rename, merge or describe topics, assign questions to a topic, or set Auto-generate","description":"Send { autoGenerate } or { expectedRevision, action, topics, to?, description?, promptIds? }. topics is a batch of up to 20 names (one for rename, merge, describe, assign and unassign). expectedRevision is required for archive, restore, delete, rename and merge and optional for add, describe, assign and unassign; a stale one returns 409 revision_conflict. Archive keeps tracked questions and history and removes the topic from writer context; delete removes the topic and clears it from its questions (they stay tracked, with every answer, and have no topic); rename moves the topic's questions to the new name; merge (to is the target) moves every tracked question and suggestion into the target and removes the topic; describe sets one line of up to 160 characters, empty clears it; assign and unassign (promptIds, 1 to 50) move questions into the topic or leave them with no topic. Adding a topic when the list is full returns 422 topics_full. Names or ids that do not apply are listed in skipped, and affectedQuestions counts questions moved. No provider call.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","anyOf":[{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"action":{"type":"string","enum":["add","archive","restore","delete","rename","merge","describe","assign","unassign"]},"topics":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"to":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":160},"promptIds":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["action","topics"],"additionalProperties":false},{"type":"object","properties":{"autoGenerate":{"type":"boolean"}},"required":["autoGenerate"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"topics":{"type":"object","properties":{"enrichmentId":{"type":"string"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"example":{"type":"boolean"},"applies":{"type":"boolean"},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"autoGenerate":{"type":"boolean"},"topics":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"origin":{"type":"string","enum":["site","ai","customer"]},"archived":{"type":"boolean"},"trackedQuestions":{"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["text","origin","archived","trackedQuestions","description"],"additionalProperties":false}},"generation":{"type":"object","properties":{"runsLimit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"runsUsed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"runsLeft":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"resetsAt":{"type":"string"},"available":{"type":"boolean"},"unavailableReason":{"anyOf":[{"type":"string","enum":["unavailable","monthly_limit","no_business_context","in_progress","plan_limit"]},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["runsLimit","runsUsed","runsLeft","resetsAt","available","unavailableReason","message"],"additionalProperties":false}},"required":["enrichmentId","revision","example","applies","limit","autoGenerate","topics","generation"],"additionalProperties":false},"changed":{"type":"boolean"},"skipped":{"type":"array","items":{"type":"string"}},"affectedQuestions":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["topics","changed","skipped"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/topics/questions":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"List a topic's questions, or the questions that could join it","description":"Tracked (active) questions. scope assigned (default) lists those saved under the topic; scope other lists the project's other tracked questions, for moving into it. Optional query filters by text; limit 1 to 200 (default 50) and offset page the list. No provider call.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"topic","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"scope","in":"query","schema":{"type":"string","enum":["assigned","other"]}},{"name":"query","in":"query","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"questions":{"type":"object","properties":{"topic":{"type":"string"},"scope":{"type":"string","enum":["assigned","other"]},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","text","topic"],"additionalProperties":false}}},"required":["topic","scope","total","questions"],"additionalProperties":false}},"required":["questions"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/topics/generate":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Generate topics with the AI writer","description":"Proposes up to 6 new topics, each with a one-line description, from the business details and tracked questions in the same request, and adds them with origin ai. Counts one of the project's monthly topic generations (KB_TOPIC_GENERATE_MONTHLY) even when nothing new is found. Needs confirm: true. 422 plan_limit when billing is enforced and the workspace has no plan, before anything is sent. 409 for monthly_limit, in_progress, topics_full or no_business_context; 503 when unavailable.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"confirm":{"type":"boolean","const":true}},"required":["confirm"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"added":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["added","nothing_new"]},"topics":{"type":"object","properties":{"enrichmentId":{"type":"string"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"example":{"type":"boolean"},"applies":{"type":"boolean"},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"autoGenerate":{"type":"boolean"},"topics":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"origin":{"type":"string","enum":["site","ai","customer"]},"archived":{"type":"boolean"},"trackedQuestions":{"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["text","origin","archived","trackedQuestions","description"],"additionalProperties":false}},"generation":{"type":"object","properties":{"runsLimit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"runsUsed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"runsLeft":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"resetsAt":{"type":"string"},"available":{"type":"boolean"},"unavailableReason":{"anyOf":[{"type":"string","enum":["unavailable","monthly_limit","no_business_context","in_progress","plan_limit"]},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["runsLimit","runsUsed","runsLeft","resetsAt","available","unavailableReason","message"],"additionalProperties":false}},"required":["enrichmentId","revision","example","applies","limit","autoGenerate","topics","generation"],"additionalProperties":false}},"required":["added","status","topics"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/brand-memory":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Read the project's memory","description":"Free text notes the writer reads before every draft, content chat reply and page proposal. Returns the revision to send back when saving. No provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"memory":{"type":"object","properties":{"content":{"type":"string"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"limits":{"type":"object","properties":{"chars":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["chars","bytes"],"additionalProperties":false}},"required":["content","revision","updatedAt","limits"],"additionalProperties":false}},"required":["memory"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"put":{"summary":"Replace the project's memory","description":"Up to 8,000 characters and 12 KiB. expectedRevision is the revision you read (0 when nothing is saved); a stale revision returns 409 revision_conflict. Applies to requests made after the save. No provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"content":{"type":"string","maxLength":8000},"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["content","expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"memory":{"type":"object","properties":{"content":{"type":"string"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"limits":{"type":"object","properties":{"chars":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["chars","bytes"],"additionalProperties":false}},"required":["content","revision","updatedAt","limits"],"additionalProperties":false}},"required":["memory"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/brand-memory/draft":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Draft the project's memory from its brand profile","description":"Markdown built from the confirmed brand profile, topics, active competitors and writing-style tone, within the 8,000 character cap. Nothing is saved and only saved memory reaches the writer. No provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"draft":{"type":"object","properties":{"content":{"type":"string"},"example":{"type":"boolean"},"truncated":{"type":"boolean"},"limits":{"type":"object","properties":{"chars":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["chars","bytes"],"additionalProperties":false}},"required":["content","example","truncated","limits"],"additionalProperties":false}},"required":["draft"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/brand-memory/process":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Process content runs left","description":"Runs left for this project this month. No provider call.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"allowance":{"type":"object","properties":{"month":{"type":"string"},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"held":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"left":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"available":{"type":"boolean"},"reason":{"anyOf":[{"type":"string","enum":["plan_limit"]},{"type":"null"}]}},"required":["month","limit","used","held","left","available","reason"],"additionalProperties":false}},"required":["allowance"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Process content into a proposed memory change","description":"Send text (up to 20,000 characters) or name with contentBase64 (PDF, TXT or MD, up to 3 MB). One AI call distils it into bullets merged under identity, positioning, audience, offerings, tone and do/don't headings, using only what the source states; the source is untrusted data. Returns a proposal and saves nothing: save it with PUT brand-memory. Uses one of the project's monthly runs; a failed run is given back. Optional current is the memory text to merge into (default: the saved memory). 422 plan_limit when billing is enforced and the workspace has no plan, before anything is read or sent.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"text":{"type":"string","maxLength":20000},"name":{"type":"string","minLength":1,"maxLength":200},"contentBase64":{"type":"string","minLength":1,"maxLength":4194312},"current":{"type":"string","maxLength":8000}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"proposal":{"type":"object","properties":{"content":{"type":"string"},"base":{"type":"string"},"addedLines":{"type":"array","items":{"type":"integer","minimum":0,"maximum":9007199254740991}},"added":{"type":"integer","minimum":0,"maximum":9007199254740991},"skipped":{"type":"integer","minimum":0,"maximum":9007199254740991},"trimmed":{"type":"integer","minimum":0,"maximum":9007199254740991},"changed":{"type":"boolean"},"sourceTruncated":{"type":"boolean"},"example":{"type":"boolean"}},"required":["content","base","addedLines","added","skipped","trimmed","changed","sourceTruncated","example"],"additionalProperties":false},"allowance":{"type":"object","properties":{"month":{"type":"string"},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"held":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"left":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"available":{"type":"boolean"},"reason":{"anyOf":[{"type":"string","enum":["plan_limit"]},{"type":"null"}]}},"required":["month","limit","used","held","left","available","reason"],"additionalProperties":false}},"required":["proposal","allowance"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/brand-context":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Read the project's geographic reach and brand context","description":"The writer reads both before every draft, content chat reply and page proposal. Returns the revision to send back when saving and the auto-detect allowance for this month. No provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"context":{"type":"object","properties":{"geographicReach":{"anyOf":[{"type":"string","enum":["global","primary_market","nationwide","regional","local"]},{"type":"null"}]},"brandContext":{"type":"string"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"limits":{"type":"object","properties":{"chars":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["chars","bytes"],"additionalProperties":false},"detect":{"type":"object","properties":{"available":{"type":"boolean"},"remaining":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","minimum":0,"maximum":9007199254740991},"reason":{"anyOf":[{"type":"string","enum":["plan_limit","no_site","limit_reached","unavailable"]},{"type":"null"}]}},"required":["available","remaining","limit","reason"],"additionalProperties":false}},"required":["geographicReach","brandContext","revision","updatedAt","limits","detect"],"additionalProperties":false}},"required":["context"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"put":{"summary":"Change the project's geographic reach and/or brand context","description":"Send only the fields you change; geographicReach null clears it. expectedRevision is the revision you read (0 when nothing is saved); a stale revision returns 409 revision_conflict. Applies to requests made after the save. No provider call or allowance use.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"geographicReach":{"anyOf":[{"type":"string","enum":["global","primary_market","nationwide","regional","local"]},{"type":"null"}]},"brandContext":{"type":"string","maxLength":2000}},"required":["expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"context":{"type":"object","properties":{"geographicReach":{"anyOf":[{"type":"string","enum":["global","primary_market","nationwide","regional","local"]},{"type":"null"}]},"brandContext":{"type":"string"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"limits":{"type":"object","properties":{"chars":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["chars","bytes"],"additionalProperties":false},"detect":{"type":"object","properties":{"available":{"type":"boolean"},"remaining":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","minimum":0,"maximum":9007199254740991},"reason":{"anyOf":[{"type":"string","enum":["plan_limit","no_site","limit_reached","unavailable"]},{"type":"null"}]}},"required":["available","remaining","limit","reason"],"additionalProperties":false}},"required":["geographicReach","brandContext","revision","updatedAt","limits","detect"],"additionalProperties":false}},"required":["context"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/brand-context/detect":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Propose brand context from the project's website","description":"Reads the site now and writes a proposal with one OpenAI call. Nothing is saved. Every call counts toward a monthly per-project limit (409 limit_reached when none are left), including one that returns no usable text (502 no_result). A site that cannot be read (409 no_readable_site) is not counted. 422 plan_limit when billing is enforced and the workspace has no plan, before the site is read.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"detection":{"type":"object","properties":{"proposal":{"type":"string"},"example":{"type":"boolean"},"sources":{"type":"array","items":{"type":"string"}},"remaining":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["proposal","example","sources","remaining","limit"],"additionalProperties":false}},"required":["detection"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/prompts/{promptId}/rewrite":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"promptId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Get the suggested rewrite of a tracked question","description":"One AI-suggested full-question rewrite per tracked question, stored for that exact text. Keeps brand names and the topic. We pay for the model call; no answer allowance is used. Apply it with PATCH /api/v1/projects/{projectId}/prompts/{promptId}; earlier answers keep their recorded wording.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"rewrite":{"type":"object","properties":{"promptId":{"type":"string"},"sourceText":{"type":"string"},"suggestion":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"dismissed":{"type":"boolean"},"reason":{"anyOf":[{"type":"string","enum":["unavailable","daily_limit","provider_failed","invalid_suggestion","plan_limit"]},{"type":"null"}]},"generated":{"type":"boolean"}},"required":["promptId","sourceText","suggestion","createdAt","dismissed","reason","generated"],"additionalProperties":false}},"required":["rewrite"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Skip the suggested rewrite of a tracked question","description":"One AI-suggested full-question rewrite per tracked question, stored for that exact text. Keeps brand names and the topic. We pay for the model call; no answer allowance is used. Apply it with PATCH /api/v1/projects/{projectId}/prompts/{promptId}; earlier answers keep their recorded wording.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"promptId":{"type":"string"},"dismissed":{"type":"boolean"}},"required":["promptId","dismissed"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/prompts/rewrite":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Get a suggested rewrite of question text that is not saved yet","description":"One AI-suggested full-question rewrite per tracked question, stored for that exact text. Keeps brand names and the topic. We pay for the model call; no answer allowance is used. Apply it with PATCH /api/v1/projects/{projectId}/prompts/{promptId}; earlier answers keep their recorded wording.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000}},"required":["text"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"rewrite":{"type":"object","properties":{"sourceText":{"type":"string"},"suggestion":{"anyOf":[{"type":"string"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string","enum":["unavailable","daily_limit","provider_failed","invalid_suggestion","plan_limit"]},{"type":"null"}]},"generated":{"type":"boolean"}},"required":["sourceText","suggestion","reason","generated"],"additionalProperties":false}},"required":["rewrite"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/prompts/rewrite/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Get suggested rewrites for up to 20 tracked questions","description":"One AI-suggested full-question rewrite per tracked question, stored for that exact text. Keeps brand names and the topic. We pay for the model call; no answer allowance is used. Apply it with PATCH /api/v1/projects/{projectId}/prompts/{promptId}; earlier answers keep their recorded wording.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"promptIds":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["promptIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"promptId":{"type":"string"},"rewrite":{"anyOf":[{"type":"object","properties":{"promptId":{"type":"string"},"sourceText":{"type":"string"},"suggestion":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"dismissed":{"type":"boolean"},"reason":{"anyOf":[{"type":"string","enum":["unavailable","daily_limit","provider_failed","invalid_suggestion","plan_limit"]},{"type":"null"}]},"generated":{"type":"boolean"}},"required":["promptId","sourceText","suggestion","createdAt","dismissed","reason","generated"],"additionalProperties":false},{"type":"null"}]},"error":{"anyOf":[{"type":"string","enum":["not_found"]},{"type":"null"}]}},"required":["promptId","rewrite","error"],"additionalProperties":false}},"generatedCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["results","generatedCount"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/question-suggestions":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"List suggested questions for a project","description":"Suggestions come from onboarding questions the customer did not pick and from indexed research already run. Listing first saves any new suggestions. No provider call and no answer allowance.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"state","in":"query","schema":{"type":"string","enum":["proposed","added","dismissed"],"default":"proposed"}},{"name":"topic","in":"query","description":"Exact topic, or none for questions without a topic.","schema":{"type":"string","maxLength":200}},{"name":"query","in":"query","description":"Case-insensitive text search.","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"suggestions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","enum":["ai_written","indexed"]},"state":{"type":"string","enum":["proposed","added","dismissed"]},"promptId":{"anyOf":[{"type":"string"},{"type":"null"}]},"intent":{"anyOf":[{"type":"string","enum":["learn","consider","purchase"]},{"type":"null"}]},"branded":{"type":"boolean"},"topicVolume":{"anyOf":[{"type":"object","properties":{"volume":{"type":"integer","minimum":0,"maximum":9007199254740991},"bars":{"type":"integer","minimum":0,"maximum":5},"month":{"type":"string"}},"required":["volume","bars","month"],"additionalProperties":false},{"type":"null"}]},"difficulty":{"anyOf":[{"type":"object","properties":{"value":{"type":"integer","minimum":0,"maximum":100},"month":{"type":"string"}},"required":["value","month"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["id","text","topic","source","state","promptId","intent","branded","topicVolume","difficulty","createdAt"],"additionalProperties":false}},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"counts":{"type":"object","properties":{"proposed":{"type":"integer","minimum":0,"maximum":9007199254740991},"added":{"type":"integer","minimum":0,"maximum":9007199254740991},"dismissed":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["proposed","added","dismissed"],"additionalProperties":false},"topics":{"type":"array","items":{"type":"object","properties":{"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"tracked":{"type":"integer","minimum":0,"maximum":9007199254740991},"proposed":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["topic","count","tracked","proposed"],"additionalProperties":false}}},"required":["suggestions","total","counts","topics"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/question-suggestions/generate":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Preview a suggest-questions run","description":"Asks the AI writer for new buyer questions from the project's confirmed business details: up to 5 topics, 1 to 10 questions per topic (perTopic, default 10) and at most 50 per run, with brandedShare (default 10), intentMix learn/consider/purchase adding up to 100 (default 20/40/40), length short or mixed (default short) and optional instructions up to 500 characters, treated as untrusted data. Each new question gets a model-written intent (learn, consider or purchase). Product-funded: no answer allowance, 5 runs per project per UTC month, one writer call per run. New questions are saved as proposed suggestions and returned with the topic volume and difficulty fetched for their topics; duplicates of tracked or already suggested questions are skipped. A run can take up to about two minutes. This preview spends nothing and shows runs left and the run limits.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"topic","in":"query","description":"Focus the run on one topic.","schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"preview":{"type":"object","properties":{"available":{"type":"boolean"},"unavailableReason":{"anyOf":[{"type":"string","enum":["unavailable","no_business_context","monthly_limit","in_progress","plan_limit"]},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"runsLimit":{"type":"integer","minimum":0,"maximum":9007199254740991},"runsUsed":{"type":"integer","minimum":0,"maximum":9007199254740991},"runsLeft":{"type":"integer","minimum":0,"maximum":9007199254740991},"resetsAt":{"type":"string"},"maxQuestions":{"type":"integer","minimum":0,"maximum":9007199254740991},"maxTopics":{"type":"integer","minimum":0,"maximum":9007199254740991},"maxPerTopic":{"type":"integer","minimum":0,"maximum":9007199254740991},"instructionsMaxChars":{"type":"integer","minimum":0,"maximum":9007199254740991},"answerUnits":{"type":"number","const":0},"fundedBy":{"type":"string","const":"product"}},"required":["available","unavailableReason","message","topic","runsLimit","runsUsed","runsLeft","resetsAt","maxQuestions","maxTopics","maxPerTopic","instructionsMaxChars","answerUnits","fundedBy"],"additionalProperties":false}},"required":["preview"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Suggest more questions","description":"Asks the AI writer for new buyer questions from the project's confirmed business details: up to 5 topics, 1 to 10 questions per topic (perTopic, default 10) and at most 50 per run, with brandedShare (default 10), intentMix learn/consider/purchase adding up to 100 (default 20/40/40), length short or mixed (default short) and optional instructions up to 500 characters, treated as untrusted data. Each new question gets a model-written intent (learn, consider or purchase). Product-funded: no answer allowance, 5 runs per project per UTC month, one writer call per run. New questions are saved as proposed suggestions and returned with the topic volume and difficulty fetched for their topics; duplicates of tracked or already suggested questions are skipped. A run can take up to about two minutes. Send confirm: true; one run per Idempotency-Key.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"confirm":{"type":"boolean","const":true},"topic":{"type":"string","minLength":1},"topics":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","minLength":1}},"perTopic":{"type":"integer","minimum":1,"maximum":10},"brandedShare":{"type":"integer","minimum":0,"maximum":100},"intentMix":{"type":"object","properties":{"learn":{"type":"integer","minimum":0,"maximum":100},"consider":{"type":"integer","minimum":0,"maximum":100},"purchase":{"type":"integer","minimum":0,"maximum":100}},"required":["learn","consider","purchase"],"additionalProperties":false},"length":{"type":"string","enum":["short","mixed"]},"instructions":{"type":"string","minLength":1,"maxLength":500}},"required":["confirm"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"attemptId":{"type":"string"},"status":{"type":"string","enum":["completed","incomplete","unknown"]},"written":{"type":"integer","minimum":0,"maximum":9007199254740991},"added":{"type":"integer","minimum":0,"maximum":9007199254740991},"duplicates":{"type":"integer","minimum":0,"maximum":9007199254740991},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"topics":{"type":"array","items":{"type":"string"}},"suggestions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string","enum":["ai_written","indexed"]},"state":{"type":"string","enum":["proposed","added","dismissed"]},"promptId":{"anyOf":[{"type":"string"},{"type":"null"}]},"intent":{"anyOf":[{"type":"string","enum":["learn","consider","purchase"]},{"type":"null"}]},"branded":{"type":"boolean"},"topicVolume":{"anyOf":[{"type":"object","properties":{"volume":{"type":"integer","minimum":0,"maximum":9007199254740991},"bars":{"type":"integer","minimum":0,"maximum":5},"month":{"type":"string"}},"required":["volume","bars","month"],"additionalProperties":false},{"type":"null"}]},"difficulty":{"anyOf":[{"type":"object","properties":{"value":{"type":"integer","minimum":0,"maximum":100},"month":{"type":"string"}},"required":["value","month"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["id","text","topic","source","state","promptId","intent","branded","topicVolume","difficulty","createdAt"],"additionalProperties":false}},"quota":{"type":"object","properties":{"runsLimit":{"type":"integer","minimum":0,"maximum":9007199254740991},"runsUsed":{"type":"integer","minimum":0,"maximum":9007199254740991},"runsLeft":{"type":"integer","minimum":0,"maximum":9007199254740991},"resetsAt":{"type":"string"}},"required":["runsLimit","runsUsed","runsLeft","resetsAt"],"additionalProperties":false}},"required":["attemptId","status","written","added","duplicates","topic","topics","suggestions","quota"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/question-suggestions/add":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Add suggested questions as tracked questions","description":"Creates tracked questions from up to 50 proposed suggestions. No scan starts.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"outcome":{"type":"string","enum":["created","already_tracked","unchanged","not_found","invalid_state"]},"promptId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","outcome","promptId"],"additionalProperties":false}},"createdCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"cadenceConsentInvalidated":{"type":"boolean"}},"required":["results","createdCount","cadenceConsentInvalidated"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/question-suggestions/dismiss":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Dismiss suggested questions","description":"Hides up to 50 proposed suggestions.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"outcome":{"type":"string","enum":["updated","unchanged","not_found","invalid_state"]}},"required":["id","outcome"],"additionalProperties":false}},"updatedCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["results","updatedCount"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/question-suggestions/restore":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Restore dismissed suggested questions","description":"Returns up to 50 dismissed suggestions to Proposed.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"outcome":{"type":"string","enum":["updated","unchanged","not_found","invalid_state"]}},"required":["id","outcome"],"additionalProperties":false}},"updatedCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["results","updatedCount"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/question-suggestions/{suggestionId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"suggestionId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"patch":{"summary":"Change a proposed suggestion's topic","description":"Sets the topic the suggestion will have when added; null clears it. Only proposed suggestions. No provider call.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"topic":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},"required":["topic"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","topic"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/keyword-research":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List recent keyword research and current request/row allowance","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped keyword response including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"input":{"type":"object","properties":{"seed":{"type":"string","minLength":1,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100}},"required":["seed","locationCode","languageCode","limit"],"additionalProperties":false},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","input","status","reservationStatus","createdAt"],"additionalProperties":false}},"quota":{"type":"object","properties":{"period":{"type":"string"},"requests":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","requests","rows"],"additionalProperties":false}},"required":["research","quota"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Confirm an unchanged quote and execute one bounded vendor request; never automatically retry","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"input":{"type":"object","properties":{"seed":{"type":"string","minLength":1,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100}},"required":["seed","locationCode","languageCode","limit"],"additionalProperties":false},"quoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["input","quoteFingerprint"],"additionalProperties":false}}}},"responses":{"201":{"description":"Scoped keyword response including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"periodId":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"input":{"type":"object","properties":{"seed":{"type":"string","minLength":1,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100}},"required":["seed","locationCode","languageCode","limit"],"additionalProperties":false},"requestConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quoteFingerprint":{"type":"string"},"ratePolicyVersion":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"reservedRows":{"type":"number"},"consumedRequests":{"type":"number"},"consumedRows":{"type":"number"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"sentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"providerTaskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"locationCode":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"languageCode":{"type":"string"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetition":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetitionLevel":{"anyOf":[{"type":"string","enum":["LOW","MEDIUM","HIGH"]},{"type":"null"}]},"cpcUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"seoDifficulty":{"anyOf":[{"type":"number"},{"type":"null"}]},"sourceUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"monthlySearches":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"year":{"type":"number"},"month":{"type":"number"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["year","month","searchVolume"],"additionalProperties":false}},{"type":"null"}]}},"required":["keyword","locationCode","languageCode","searchVolume","adsCompetition","adsCompetitionLevel","cpcUsd","seoDifficulty","sourceUpdatedAt","monthlySearches"],"additionalProperties":false}},{"type":"null"}]},"totalAvailable":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","jobId","status","sentAt","receivedAt","providerTaskId","providerStatusCode","failure","billing","responseHash","candidates","totalAvailable","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["id","orgId","projectId","periodId","createdBy","input","requestConfig","quoteFingerprint","ratePolicyVersion","status","reservationStatus","reservedRows","consumedRequests","consumedRows","createdAt","updatedAt","attempt"],"additionalProperties":false},{"type":"null"}]},"quota":{"type":"object","properties":{"period":{"type":"string"},"requests":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","requests","rows"],"additionalProperties":false}},"required":["research"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/keyword-research/markets":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read free vendor supported country/language metadata","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped keyword response including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"markets":{"type":"array","items":{"type":"object","properties":{"locationCode":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"languages":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}},"required":["code","name"],"additionalProperties":false}}},"required":["locationCode","name","languages"],"additionalProperties":false}},"acquiredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"source":{"type":"string","format":"uri"}},"required":["markets","acquiredAt","source"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/keyword-research/preview":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Preview exact scope and finite quota impact without spending","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"seed":{"type":"string","minLength":1,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100}},"required":["seed","locationCode","languageCode","limit"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped keyword response including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"preview":{"type":"object","properties":{"input":{"type":"object","properties":{"seed":{"type":"string","minLength":1,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100}},"required":["seed","locationCode","languageCode","limit"],"additionalProperties":false},"fingerprint":{"type":"string"},"quota":{"type":"object","properties":{"period":{"type":"string"},"requests":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","requests","rows"],"additionalProperties":false},"allowed":{"type":"boolean"},"reason":{"anyOf":[{"type":"string","enum":["research_allowance","storage_limit"]},{"type":"null"}]},"storage":{"type":"object","properties":{"orgUsedOrHeldBytes":{"type":"number"},"orgLimitBytes":{"type":"number"},"deploymentLimitBytes":{"type":"number"},"reservationBytes":{"type":"number"}},"required":["orgUsedOrHeldBytes","orgLimitBytes","deploymentLimitBytes","reservationBytes"],"additionalProperties":false},"plannedRequests":{"type":"number","const":1},"maximumCandidateRows":{"type":"number"},"remainingAfter":{"type":"object","properties":{"requests":{"type":"number"},"rows":{"type":"number"}},"required":["requests","rows"],"additionalProperties":false},"source":{"type":"object","properties":{"provider":{"type":"string","const":"dataforseo"},"collectionMethod":{"type":"string","const":"vendor_api"},"dataset":{"type":"string"},"volumeMeaning":{"type":"string"}},"required":["provider","collectionMethod","dataset","volumeMeaning"],"additionalProperties":false},"requestConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["input","fingerprint","quota","allowed","reason","storage","plannedRequests","maximumCandidateRows","remainingAfter","source","requestConfig"],"additionalProperties":false}},"required":["preview"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/keyword-research/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read up to 100 scoped research snapshots","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped keyword response including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"periodId":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"input":{"type":"object","properties":{"seed":{"type":"string","minLength":1,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100}},"required":["seed","locationCode","languageCode","limit"],"additionalProperties":false},"requestConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quoteFingerprint":{"type":"string"},"ratePolicyVersion":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"reservedRows":{"type":"number"},"consumedRequests":{"type":"number"},"consumedRows":{"type":"number"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"sentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"providerTaskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"locationCode":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"languageCode":{"type":"string"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetition":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetitionLevel":{"anyOf":[{"type":"string","enum":["LOW","MEDIUM","HIGH"]},{"type":"null"}]},"cpcUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"seoDifficulty":{"anyOf":[{"type":"number"},{"type":"null"}]},"sourceUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"monthlySearches":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"year":{"type":"number"},"month":{"type":"number"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["year","month","searchVolume"],"additionalProperties":false}},{"type":"null"}]}},"required":["keyword","locationCode","languageCode","searchVolume","adsCompetition","adsCompetitionLevel","cpcUsd","seoDifficulty","sourceUpdatedAt","monthlySearches"],"additionalProperties":false}},{"type":"null"}]},"totalAvailable":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","jobId","status","sentAt","receivedAt","providerTaskId","providerStatusCode","failure","billing","responseHash","candidates","totalAvailable","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["id","orgId","projectId","periodId","createdBy","input","requestConfig","quoteFingerprint","ratePolicyVersion","status","reservationStatus","reservedRows","consumedRequests","consumedRows","createdAt","updatedAt","attempt"],"additionalProperties":false}}},"required":["research"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/keyword-research/{researchId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"researchId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read candidates and the actual provider execution receipt","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped keyword response including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"periodId":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"input":{"type":"object","properties":{"seed":{"type":"string","minLength":1,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100}},"required":["seed","locationCode","languageCode","limit"],"additionalProperties":false},"requestConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quoteFingerprint":{"type":"string"},"ratePolicyVersion":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"reservedRows":{"type":"number"},"consumedRequests":{"type":"number"},"consumedRows":{"type":"number"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"sentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"providerTaskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"locationCode":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"languageCode":{"type":"string"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetition":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetitionLevel":{"anyOf":[{"type":"string","enum":["LOW","MEDIUM","HIGH"]},{"type":"null"}]},"cpcUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"seoDifficulty":{"anyOf":[{"type":"number"},{"type":"null"}]},"sourceUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"monthlySearches":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"year":{"type":"number"},"month":{"type":"number"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["year","month","searchVolume"],"additionalProperties":false}},{"type":"null"}]}},"required":["keyword","locationCode","languageCode","searchVolume","adsCompetition","adsCompetitionLevel","cpcUsd","seoDifficulty","sourceUpdatedAt","monthlySearches"],"additionalProperties":false}},{"type":"null"}]},"totalAvailable":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","jobId","status","sentAt","receivedAt","providerTaskId","providerStatusCode","failure","billing","responseHash","candidates","totalAvailable","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["id","orgId","projectId","periodId","createdBy","input","requestConfig","quoteFingerprint","ratePolicyVersion","status","reservationStatus","reservedRows","consumedRequests","consumedRows","createdAt","updatedAt","attempt"],"additionalProperties":false},{"type":"null"}]},"quota":{"type":"object","properties":{"period":{"type":"string"},"requests":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","requests","rows"],"additionalProperties":false}},"required":["research"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/keyword-research/{researchId}/evidence":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"researchId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read the immutable raw vendor body and integrity hash without refreshing","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped keyword response including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"evidence":{"type":"object","properties":{"rawResponse":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["rawResponse","responseHash","receivedAt"],"additionalProperties":false}},"required":["evidence"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/keyword-research/{researchId}/reconcile":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"researchId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Reconcile stored evidence or expired execution without sending a new provider request","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped keyword response including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"periodId":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"input":{"type":"object","properties":{"seed":{"type":"string","minLength":1,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100}},"required":["seed","locationCode","languageCode","limit"],"additionalProperties":false},"requestConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quoteFingerprint":{"type":"string"},"ratePolicyVersion":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"reservedRows":{"type":"number"},"consumedRequests":{"type":"number"},"consumedRows":{"type":"number"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"sentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"providerTaskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidates":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"locationCode":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"languageCode":{"type":"string"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetition":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetitionLevel":{"anyOf":[{"type":"string","enum":["LOW","MEDIUM","HIGH"]},{"type":"null"}]},"cpcUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"seoDifficulty":{"anyOf":[{"type":"number"},{"type":"null"}]},"sourceUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"monthlySearches":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"year":{"type":"number"},"month":{"type":"number"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["year","month","searchVolume"],"additionalProperties":false}},{"type":"null"}]}},"required":["keyword","locationCode","languageCode","searchVolume","adsCompetition","adsCompetitionLevel","cpcUsd","seoDifficulty","sourceUpdatedAt","monthlySearches"],"additionalProperties":false}},{"type":"null"}]},"totalAvailable":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","jobId","status","sentAt","receivedAt","providerTaskId","providerStatusCode","failure","billing","responseHash","candidates","totalAvailable","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["id","orgId","projectId","periodId","createdBy","input","requestConfig","quoteFingerprint","ratePolicyVersion","status","reservationStatus","reservedRows","consumedRequests","consumedRows","createdAt","updatedAt","attempt"],"additionalProperties":false},{"type":"null"}]},"quota":{"type":"object","properties":{"period":{"type":"string"},"requests":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","requests","rows"],"additionalProperties":false}},"required":["research"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/keywords":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List saved keyword selections and copied original evidence","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped keyword response including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"sourceJobId":{"anyOf":[{"type":"string"},{"type":"null"}]},"keyword":{"type":"string"},"locationCode":{"type":"number"},"languageCode":{"type":"string"},"sourceEvidence":{"type":"object","properties":{"candidate":{"type":"object","properties":{"keyword":{"type":"string"},"locationCode":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"languageCode":{"type":"string"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetition":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetitionLevel":{"anyOf":[{"type":"string","enum":["LOW","MEDIUM","HIGH"]},{"type":"null"}]},"cpcUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"seoDifficulty":{"anyOf":[{"type":"number"},{"type":"null"}]},"sourceUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"monthlySearches":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"year":{"type":"number"},"month":{"type":"number"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["year","month","searchVolume"],"additionalProperties":false}},{"type":"null"}]}},"required":["keyword","locationCode","languageCode","searchVolume","adsCompetition","adsCompetitionLevel","cpcUsd","seoDifficulty","sourceUpdatedAt","monthlySearches"],"additionalProperties":false},"acquiredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"provider":{"type":"string","const":"dataforseo"},"collectionMethod":{"type":"string","const":"vendor_api"},"taskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"type":"string"}},"required":["candidate","acquiredAt","provider","collectionMethod","taskId","responseHash"],"additionalProperties":false},"notes":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","orgId","projectId","sourceJobId","keyword","locationCode","languageCode","sourceEvidence","notes","createdBy","createdAt","updatedAt"],"additionalProperties":false}}},"required":["keywords"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Save selected completed-research candidate indices in one batch without paid work","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"researchId":{"type":"string","minLength":1},"indices":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"integer","minimum":0,"maximum":99}}},"required":["researchId","indices"],"additionalProperties":false}}}},"responses":{"201":{"description":"Scoped keyword response including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"sourceJobId":{"anyOf":[{"type":"string"},{"type":"null"}]},"keyword":{"type":"string"},"locationCode":{"type":"number"},"languageCode":{"type":"string"},"sourceEvidence":{"type":"object","properties":{"candidate":{"type":"object","properties":{"keyword":{"type":"string"},"locationCode":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"languageCode":{"type":"string"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetition":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetitionLevel":{"anyOf":[{"type":"string","enum":["LOW","MEDIUM","HIGH"]},{"type":"null"}]},"cpcUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"seoDifficulty":{"anyOf":[{"type":"number"},{"type":"null"}]},"sourceUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"monthlySearches":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"year":{"type":"number"},"month":{"type":"number"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["year","month","searchVolume"],"additionalProperties":false}},{"type":"null"}]}},"required":["keyword","locationCode","languageCode","searchVolume","adsCompetition","adsCompetitionLevel","cpcUsd","seoDifficulty","sourceUpdatedAt","monthlySearches"],"additionalProperties":false},"acquiredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"provider":{"type":"string","const":"dataforseo"},"collectionMethod":{"type":"string","const":"vendor_api"},"taskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"type":"string"}},"required":["candidate","acquiredAt","provider","collectionMethod","taskId","responseHash"],"additionalProperties":false},"notes":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","orgId","projectId","sourceJobId","keyword","locationCode","languageCode","sourceEvidence","notes","createdBy","createdAt","updatedAt"],"additionalProperties":false}}},"required":["keywords"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/keywords/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read saved keywords by scoped ids","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped keyword response including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"sourceJobId":{"anyOf":[{"type":"string"},{"type":"null"}]},"keyword":{"type":"string"},"locationCode":{"type":"number"},"languageCode":{"type":"string"},"sourceEvidence":{"type":"object","properties":{"candidate":{"type":"object","properties":{"keyword":{"type":"string"},"locationCode":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"languageCode":{"type":"string"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetition":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetitionLevel":{"anyOf":[{"type":"string","enum":["LOW","MEDIUM","HIGH"]},{"type":"null"}]},"cpcUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"seoDifficulty":{"anyOf":[{"type":"number"},{"type":"null"}]},"sourceUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"monthlySearches":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"year":{"type":"number"},"month":{"type":"number"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["year","month","searchVolume"],"additionalProperties":false}},{"type":"null"}]}},"required":["keyword","locationCode","languageCode","searchVolume","adsCompetition","adsCompetitionLevel","cpcUsd","seoDifficulty","sourceUpdatedAt","monthlySearches"],"additionalProperties":false},"acquiredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"provider":{"type":"string","const":"dataforseo"},"collectionMethod":{"type":"string","const":"vendor_api"},"taskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"type":"string"}},"required":["candidate","acquiredAt","provider","collectionMethod","taskId","responseHash"],"additionalProperties":false},"notes":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","orgId","projectId","sourceJobId","keyword","locationCode","languageCode","sourceEvidence","notes","createdBy","createdAt","updatedAt"],"additionalProperties":false}}},"required":["keywords"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete saved selections while retaining research billing and evidence","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","minLength":1}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped keyword response including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"deletedIds":{"type":"array","items":{"type":"string"}}},"required":["deletedIds"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/keyword-clusters":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List manual keyword groups","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Manual group and source evidence","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"clusters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"title":{"type":"string"},"rationale":{"type":"string"},"targetUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"targetNeedsReview":{"type":"boolean"},"memberCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","orgId","projectId","title","rationale","targetUrl","revision","createdBy","createdAt","updatedAt","targetNeedsReview","memberCount"],"additionalProperties":false}}},"required":["clusters"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a manual group without provider calls","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"rationale":{"default":"","type":"string","maxLength":2000},"targetUrl":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"keywordIds":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","minLength":1}}},"required":["title","rationale","keywordIds"],"additionalProperties":false}}}},"responses":{"201":{"description":"Manual group and source evidence","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"cluster":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"title":{"type":"string"},"rationale":{"type":"string"},"targetUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"targetNeedsReview":{"type":"boolean"},"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"clusterId":{"type":"string"},"savedKeywordId":{"anyOf":[{"type":"string"},{"type":"null"}]},"keywordProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"keywordOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"origin":{"type":"string","enum":["real","example","unknown"]},"sourceSnapshot":{"type":"object","properties":{"savedKeywordId":{"type":"string"},"sourceJobId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceRow":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"taskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"type":"string"},"acquiredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"provider":{"type":"string","const":"dataforseo"},"collectionMethod":{"type":"string","const":"vendor_api"},"keyword":{"type":"string"},"locationCode":{"type":"number"},"languageCode":{"type":"string"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetition":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetitionLevel":{"anyOf":[{"type":"string","enum":["LOW","MEDIUM","HIGH"]},{"type":"null"}]},"cpcUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"seoDifficulty":{"anyOf":[{"type":"number"},{"type":"null"}]},"sourceUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["savedKeywordId","sourceJobId","sourceRow","taskId","responseHash","acquiredAt","provider","collectionMethod","keyword","locationCode","languageCode","searchVolume","adsCompetition","adsCompetitionLevel","cpcUsd","seoDifficulty","sourceUpdatedAt"],"additionalProperties":false},"sourceRemoved":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","orgId","projectId","clusterId","savedKeywordId","keywordProjectId","keywordOrgId","origin","sourceSnapshot","sourceRemoved","createdAt"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["shared_keyword","shared_target"]},"clusterId":{"type":"string"},"value":{"type":"string"}},"required":["kind","clusterId","value"],"additionalProperties":false}}},"required":["id","orgId","projectId","title","rationale","targetUrl","revision","createdBy","createdAt","updatedAt","targetNeedsReview","members","warnings"],"additionalProperties":false}},"required":["cluster"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/keyword-clusters/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read up to 25 scoped groups","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"maxItems":25,"type":"array","items":{"type":"string","minLength":1}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Manual group and source evidence","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"clusters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"title":{"type":"string"},"rationale":{"type":"string"},"targetUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"targetNeedsReview":{"type":"boolean"},"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"clusterId":{"type":"string"},"savedKeywordId":{"anyOf":[{"type":"string"},{"type":"null"}]},"keywordProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"keywordOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"origin":{"type":"string","enum":["real","example","unknown"]},"sourceSnapshot":{"type":"object","properties":{"savedKeywordId":{"type":"string"},"sourceJobId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceRow":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"taskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"type":"string"},"acquiredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"provider":{"type":"string","const":"dataforseo"},"collectionMethod":{"type":"string","const":"vendor_api"},"keyword":{"type":"string"},"locationCode":{"type":"number"},"languageCode":{"type":"string"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetition":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetitionLevel":{"anyOf":[{"type":"string","enum":["LOW","MEDIUM","HIGH"]},{"type":"null"}]},"cpcUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"seoDifficulty":{"anyOf":[{"type":"number"},{"type":"null"}]},"sourceUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["savedKeywordId","sourceJobId","sourceRow","taskId","responseHash","acquiredAt","provider","collectionMethod","keyword","locationCode","languageCode","searchVolume","adsCompetition","adsCompetitionLevel","cpcUsd","seoDifficulty","sourceUpdatedAt"],"additionalProperties":false},"sourceRemoved":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","orgId","projectId","clusterId","savedKeywordId","keywordProjectId","keywordOrgId","origin","sourceSnapshot","sourceRemoved","createdAt"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["shared_keyword","shared_target"]},"clusterId":{"type":"string"},"value":{"type":"string"}},"required":["kind","clusterId","value"],"additionalProperties":false}}},"required":["id","orgId","projectId","title","rationale","targetUrl","revision","createdBy","createdAt","updatedAt","targetNeedsReview","members","warnings"],"additionalProperties":false}}},"required":["clusters"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/keyword-clusters/{clusterId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"clusterId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read source evidence and overlap warnings","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Manual group and source evidence","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"cluster":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"title":{"type":"string"},"rationale":{"type":"string"},"targetUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"targetNeedsReview":{"type":"boolean"},"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"clusterId":{"type":"string"},"savedKeywordId":{"anyOf":[{"type":"string"},{"type":"null"}]},"keywordProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"keywordOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"origin":{"type":"string","enum":["real","example","unknown"]},"sourceSnapshot":{"type":"object","properties":{"savedKeywordId":{"type":"string"},"sourceJobId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceRow":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"taskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"type":"string"},"acquiredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"provider":{"type":"string","const":"dataforseo"},"collectionMethod":{"type":"string","const":"vendor_api"},"keyword":{"type":"string"},"locationCode":{"type":"number"},"languageCode":{"type":"string"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetition":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetitionLevel":{"anyOf":[{"type":"string","enum":["LOW","MEDIUM","HIGH"]},{"type":"null"}]},"cpcUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"seoDifficulty":{"anyOf":[{"type":"number"},{"type":"null"}]},"sourceUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["savedKeywordId","sourceJobId","sourceRow","taskId","responseHash","acquiredAt","provider","collectionMethod","keyword","locationCode","languageCode","searchVolume","adsCompetition","adsCompetitionLevel","cpcUsd","seoDifficulty","sourceUpdatedAt"],"additionalProperties":false},"sourceRemoved":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","orgId","projectId","clusterId","savedKeywordId","keywordProjectId","keywordOrgId","origin","sourceSnapshot","sourceRemoved","createdAt"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["shared_keyword","shared_target"]},"clusterId":{"type":"string"},"value":{"type":"string"}},"required":["kind","clusterId","value"],"additionalProperties":false}}},"required":["id","orgId","projectId","title","rationale","targetUrl","revision","createdBy","createdAt","updatedAt","targetNeedsReview","members","warnings"],"additionalProperties":false}},"required":["cluster"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Edit a group at its expected revision","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"title":{"type":"string","minLength":1,"maxLength":200},"rationale":{"type":"string","maxLength":2000},"targetUrl":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}]},"addKeywordIds":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"removeMemberIds":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","minLength":1}}},"required":["expectedRevision","addKeywordIds","removeMemberIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Manual group and source evidence","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"cluster":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"title":{"type":"string"},"rationale":{"type":"string"},"targetUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"revision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"targetNeedsReview":{"type":"boolean"},"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"clusterId":{"type":"string"},"savedKeywordId":{"anyOf":[{"type":"string"},{"type":"null"}]},"keywordProjectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"keywordOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"origin":{"type":"string","enum":["real","example","unknown"]},"sourceSnapshot":{"type":"object","properties":{"savedKeywordId":{"type":"string"},"sourceJobId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceRow":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"taskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"type":"string"},"acquiredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"provider":{"type":"string","const":"dataforseo"},"collectionMethod":{"type":"string","const":"vendor_api"},"keyword":{"type":"string"},"locationCode":{"type":"number"},"languageCode":{"type":"string"},"searchVolume":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetition":{"anyOf":[{"type":"number"},{"type":"null"}]},"adsCompetitionLevel":{"anyOf":[{"type":"string","enum":["LOW","MEDIUM","HIGH"]},{"type":"null"}]},"cpcUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"seoDifficulty":{"anyOf":[{"type":"number"},{"type":"null"}]},"sourceUpdatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["savedKeywordId","sourceJobId","sourceRow","taskId","responseHash","acquiredAt","provider","collectionMethod","keyword","locationCode","languageCode","searchVolume","adsCompetition","adsCompetitionLevel","cpcUsd","seoDifficulty","sourceUpdatedAt"],"additionalProperties":false},"sourceRemoved":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","orgId","projectId","clusterId","savedKeywordId","keywordProjectId","keywordOrgId","origin","sourceSnapshot","sourceRemoved","createdAt"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["shared_keyword","shared_target"]},"clusterId":{"type":"string"},"value":{"type":"string"}},"required":["kind","clusterId","value"],"additionalProperties":false}}},"required":["id","orgId","projectId","title","rationale","targetUrl","revision","createdBy","createdAt","updatedAt","targetNeedsReview","members","warnings"],"additionalProperties":false}},"required":["cluster"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a group at its expected revision","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Manual group and source evidence","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"deletedClusterId":{"type":"string"}},"required":["deletedClusterId"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/serp":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List up to 20 captured Google SERP observations without refresh","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped SERP evidence including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"snapshots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"scope":{"type":"object","properties":{"keyword":{"type":"string","minLength":1,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"device":{"type":"string","enum":["desktop","mobile"]},"targetDomain":{"type":"string","minLength":1},"includeSubdomains":{"type":"boolean"}},"required":["keyword","locationCode","languageCode","device","targetDomain","includeSubdomains"],"additionalProperties":false},"status":{"type":"string"},"reservationStatus":{"type":"string"},"policyVersion":{"type":"string"},"effectiveKeyword":{"anyOf":[{"type":"string"},{"type":"null"}]},"rankReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["id","scope","status","reservationStatus","policyVersion","effectiveKeyword","rankReason","createdAt"],"additionalProperties":false}}},"required":["snapshots"],"additionalProperties":false},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Confirm an unchanged quote and acquire one bounded SERP","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"input":{"type":"object","properties":{"savedKeywordId":{"type":"string","minLength":1},"device":{"type":"string","enum":["desktop","mobile"]},"expectedProjectDomain":{"type":"string","minLength":1},"includeSubdomains":{"type":"boolean"}},"required":["savedKeywordId","device","expectedProjectDomain","includeSubdomains"],"additionalProperties":false},"quoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["input","quoteFingerprint"],"additionalProperties":false}}}},"responses":{"201":{"description":"Scoped SERP evidence including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"snapshot":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"savedKeywordId":{"anyOf":[{"type":"string"},{"type":"null"}]},"scope":{"type":"object","properties":{"keyword":{"type":"string","minLength":1,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"device":{"type":"string","enum":["desktop","mobile"]},"targetDomain":{"type":"string","minLength":1},"includeSubdomains":{"type":"boolean"}},"required":["keyword","locationCode","languageCode","device","targetDomain","includeSubdomains"],"additionalProperties":false},"policyVersion":{"type":"string"},"status":{"type":"string"},"reservationStatus":{"type":"string"},"createdAt":{"type":"string"},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"receivedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"receipt":{"anyOf":[{"type":"object","properties":{"collectionMethod":{"type":"string","const":"vendor_api"},"status":{"type":"string","enum":["completed","failed","unknown"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"taskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"observedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"effectiveKeyword":{"anyOf":[{"type":"string"},{"type":"null"}]},"pagesCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"itemsCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"organicCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"maxOrganicRank":{"anyOf":[{"type":"number"},{"type":"null"}]},"features":{"type":"array","items":{"type":"string"}},"items":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"rankGroup":{"anyOf":[{"type":"number"},{"type":"null"}]},"rankAbsolute":{"anyOf":[{"type":"number"},{"type":"null"}]},"page":{"anyOf":[{"type":"number"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"attribution":{"type":"string","enum":["match","other","unknown"]}},"required":["type","rankGroup","rankAbsolute","page","url","title","attribution"],"additionalProperties":false}},"rank":{"type":"object","properties":{"status":{"type":"string","enum":["found","observed_incomplete","not_observed","unknown"]},"rankGroup":{"anyOf":[{"type":"number"},{"type":"null"}]},"rankAbsolute":{"anyOf":[{"type":"number"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","rankGroup","rankAbsolute","reason"],"additionalProperties":false}},"required":["collectionMethod","status","reason","taskId","providerStatusCode","billing","observedAt","effectiveKeyword","pagesCount","itemsCount","organicCount","maxOrganicRank","features","items","rank"],"additionalProperties":false},{"type":"null"}]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","receivedAt","responseHash","receipt","failure"],"additionalProperties":{}},{"type":"null"}]}},"required":["id","orgId","projectId","savedKeywordId","scope","policyVersion","status","reservationStatus","createdAt","attempt"],"additionalProperties":{}},{"type":"null"}]}},"required":["snapshot"],"additionalProperties":false},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/serp/preview":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Preview exact scope and finite allowance before acquisition","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"savedKeywordId":{"type":"string","minLength":1},"device":{"type":"string","enum":["desktop","mobile"]},"expectedProjectDomain":{"type":"string","minLength":1},"includeSubdomains":{"type":"boolean"}},"required":["savedKeywordId","device","expectedProjectDomain","includeSubdomains"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped SERP evidence including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"preview":{"type":"object","properties":{"input":{"type":"object","properties":{"savedKeywordId":{"type":"string","minLength":1},"device":{"type":"string","enum":["desktop","mobile"]},"expectedProjectDomain":{"type":"string","minLength":1},"includeSubdomains":{"type":"boolean"}},"required":["savedKeywordId","device","expectedProjectDomain","includeSubdomains"],"additionalProperties":false},"scope":{"type":"object","properties":{"keyword":{"type":"string","minLength":1,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"device":{"type":"string","enum":["desktop","mobile"]},"targetDomain":{"type":"string","minLength":1},"includeSubdomains":{"type":"boolean"}},"required":["keyword","locationCode","languageCode","device","targetDomain","includeSubdomains"],"additionalProperties":false},"fingerprint":{"type":"string"},"quota":{"type":"object","properties":{"month":{"type":"string"},"limit":{"type":"number"},"held":{"type":"number"},"used":{"type":"number"},"remaining":{"type":"number"},"storage":{"type":"object","properties":{"orgUsedOrHeldBytes":{"type":"number"},"orgLimitBytes":{"type":"number"},"deploymentLimitBytes":{"type":"number"},"reservationBytes":{"type":"number"}},"required":["orgUsedOrHeldBytes","orgLimitBytes","deploymentLimitBytes","reservationBytes"],"additionalProperties":false}},"required":["month","limit","held","used","remaining","storage"],"additionalProperties":false},"allowed":{"type":"boolean"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"plannedSnapshots":{"type":"number"},"maximumSupplierPages":{"type":"number"},"remainingAfter":{"type":"number"},"requestConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"collectionMethod":{"type":"string"}},"required":["input","scope","fingerprint","quota","allowed","reason","plannedSnapshots","maximumSupplierPages","remainingAfter","requestConfig","collectionMethod"],"additionalProperties":false}},"required":["preview"],"additionalProperties":false},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/serp/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read up to ten scoped SERP snapshots","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped SERP evidence including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"snapshots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"savedKeywordId":{"anyOf":[{"type":"string"},{"type":"null"}]},"scope":{"type":"object","properties":{"keyword":{"type":"string","minLength":1,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"device":{"type":"string","enum":["desktop","mobile"]},"targetDomain":{"type":"string","minLength":1},"includeSubdomains":{"type":"boolean"}},"required":["keyword","locationCode","languageCode","device","targetDomain","includeSubdomains"],"additionalProperties":false},"policyVersion":{"type":"string"},"status":{"type":"string"},"reservationStatus":{"type":"string"},"createdAt":{"type":"string"},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"receivedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"receipt":{"anyOf":[{"type":"object","properties":{"collectionMethod":{"type":"string","const":"vendor_api"},"status":{"type":"string","enum":["completed","failed","unknown"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"taskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"observedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"effectiveKeyword":{"anyOf":[{"type":"string"},{"type":"null"}]},"pagesCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"itemsCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"organicCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"maxOrganicRank":{"anyOf":[{"type":"number"},{"type":"null"}]},"features":{"type":"array","items":{"type":"string"}},"items":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"rankGroup":{"anyOf":[{"type":"number"},{"type":"null"}]},"rankAbsolute":{"anyOf":[{"type":"number"},{"type":"null"}]},"page":{"anyOf":[{"type":"number"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"attribution":{"type":"string","enum":["match","other","unknown"]}},"required":["type","rankGroup","rankAbsolute","page","url","title","attribution"],"additionalProperties":false}},"rank":{"type":"object","properties":{"status":{"type":"string","enum":["found","observed_incomplete","not_observed","unknown"]},"rankGroup":{"anyOf":[{"type":"number"},{"type":"null"}]},"rankAbsolute":{"anyOf":[{"type":"number"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","rankGroup","rankAbsolute","reason"],"additionalProperties":false}},"required":["collectionMethod","status","reason","taskId","providerStatusCode","billing","observedAt","effectiveKeyword","pagesCount","itemsCount","organicCount","maxOrganicRank","features","items","rank"],"additionalProperties":false},{"type":"null"}]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","receivedAt","responseHash","receipt","failure"],"additionalProperties":{}},{"type":"null"}]}},"required":["id","orgId","projectId","savedKeywordId","scope","policyVersion","status","reservationStatus","createdAt","attempt"],"additionalProperties":{}}}},"required":["snapshots"],"additionalProperties":false},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/serp/{snapshotId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"snapshotId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read captured results, position and supplier receipt","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped SERP evidence including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"snapshot":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"savedKeywordId":{"anyOf":[{"type":"string"},{"type":"null"}]},"scope":{"type":"object","properties":{"keyword":{"type":"string","minLength":1,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"device":{"type":"string","enum":["desktop","mobile"]},"targetDomain":{"type":"string","minLength":1},"includeSubdomains":{"type":"boolean"}},"required":["keyword","locationCode","languageCode","device","targetDomain","includeSubdomains"],"additionalProperties":false},"policyVersion":{"type":"string"},"status":{"type":"string"},"reservationStatus":{"type":"string"},"createdAt":{"type":"string"},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"receivedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"receipt":{"anyOf":[{"type":"object","properties":{"collectionMethod":{"type":"string","const":"vendor_api"},"status":{"type":"string","enum":["completed","failed","unknown"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"taskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"observedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"effectiveKeyword":{"anyOf":[{"type":"string"},{"type":"null"}]},"pagesCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"itemsCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"organicCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"maxOrganicRank":{"anyOf":[{"type":"number"},{"type":"null"}]},"features":{"type":"array","items":{"type":"string"}},"items":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"rankGroup":{"anyOf":[{"type":"number"},{"type":"null"}]},"rankAbsolute":{"anyOf":[{"type":"number"},{"type":"null"}]},"page":{"anyOf":[{"type":"number"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"attribution":{"type":"string","enum":["match","other","unknown"]}},"required":["type","rankGroup","rankAbsolute","page","url","title","attribution"],"additionalProperties":false}},"rank":{"type":"object","properties":{"status":{"type":"string","enum":["found","observed_incomplete","not_observed","unknown"]},"rankGroup":{"anyOf":[{"type":"number"},{"type":"null"}]},"rankAbsolute":{"anyOf":[{"type":"number"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","rankGroup","rankAbsolute","reason"],"additionalProperties":false}},"required":["collectionMethod","status","reason","taskId","providerStatusCode","billing","observedAt","effectiveKeyword","pagesCount","itemsCount","organicCount","maxOrganicRank","features","items","rank"],"additionalProperties":false},{"type":"null"}]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","receivedAt","responseHash","receipt","failure"],"additionalProperties":{}},{"type":"null"}]}},"required":["id","orgId","projectId","savedKeywordId","scope","policyVersion","status","reservationStatus","createdAt","attempt"],"additionalProperties":{}},{"type":"null"}]}},"required":["snapshot"],"additionalProperties":false},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/serp/{snapshotId}/evidence":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"snapshotId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read immutable raw provider evidence and hash","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped SERP evidence including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"evidence":{"anyOf":[{"type":"object","properties":{"rawResponse":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["rawResponse","responseHash","receivedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["evidence"],"additionalProperties":false},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/serp/{snapshotId}/reconcile":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"snapshotId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Reconcile an existing attempt without a provider request","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped SERP evidence including provenance and usage metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"snapshot":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"savedKeywordId":{"anyOf":[{"type":"string"},{"type":"null"}]},"scope":{"type":"object","properties":{"keyword":{"type":"string","minLength":1,"maxLength":250},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"device":{"type":"string","enum":["desktop","mobile"]},"targetDomain":{"type":"string","minLength":1},"includeSubdomains":{"type":"boolean"}},"required":["keyword","locationCode","languageCode","device","targetDomain","includeSubdomains"],"additionalProperties":false},"policyVersion":{"type":"string"},"status":{"type":"string"},"reservationStatus":{"type":"string"},"createdAt":{"type":"string"},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"receivedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"receipt":{"anyOf":[{"type":"object","properties":{"collectionMethod":{"type":"string","const":"vendor_api"},"status":{"type":"string","enum":["completed","failed","unknown"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"taskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"observedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"effectiveKeyword":{"anyOf":[{"type":"string"},{"type":"null"}]},"pagesCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"itemsCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"organicCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"maxOrganicRank":{"anyOf":[{"type":"number"},{"type":"null"}]},"features":{"type":"array","items":{"type":"string"}},"items":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"rankGroup":{"anyOf":[{"type":"number"},{"type":"null"}]},"rankAbsolute":{"anyOf":[{"type":"number"},{"type":"null"}]},"page":{"anyOf":[{"type":"number"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"attribution":{"type":"string","enum":["match","other","unknown"]}},"required":["type","rankGroup","rankAbsolute","page","url","title","attribution"],"additionalProperties":false}},"rank":{"type":"object","properties":{"status":{"type":"string","enum":["found","observed_incomplete","not_observed","unknown"]},"rankGroup":{"anyOf":[{"type":"number"},{"type":"null"}]},"rankAbsolute":{"anyOf":[{"type":"number"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","rankGroup","rankAbsolute","reason"],"additionalProperties":false}},"required":["collectionMethod","status","reason","taskId","providerStatusCode","billing","observedAt","effectiveKeyword","pagesCount","itemsCount","organicCount","maxOrganicRank","features","items","rank"],"additionalProperties":false},{"type":"null"}]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","receivedAt","responseHash","receipt","failure"],"additionalProperties":{}},{"type":"null"}]}},"required":["id","orgId","projectId","savedKeywordId","scope","policyVersion","status","reservationStatus","createdAt","attempt"],"additionalProperties":{}},{"type":"null"}]}},"required":["snapshot"],"additionalProperties":false},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/backlinks":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List vendor snapshots and allowance","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped evidence and source metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"scope":{"type":"object","properties":{"includeSubdomains":{"type":"boolean"},"excludeInternal":{"type":"boolean"},"confirmRootScope":{"type":"boolean"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100},"target":{"type":"string"},"savedDomain":{"type":"string"},"normalizedFromWww":{"type":"boolean"}},"required":["includeSubdomains","excludeInternal","confirmRootScope","limit","target","savedDomain","normalizedFromWww"],"additionalProperties":false},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["id","scope","status","reservationStatus","createdAt","example"],"additionalProperties":false}},"quota":{"type":"object","properties":{"period":{"type":"string"},"tasks":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","tasks","rows"],"additionalProperties":false}},"required":["research","quota"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Acquire one confirmed index snapshot","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"input":{"type":"object","properties":{"includeSubdomains":{"type":"boolean"},"excludeInternal":{"type":"boolean"},"confirmRootScope":{"type":"boolean"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100}},"required":["includeSubdomains","excludeInternal","confirmRootScope","limit"],"additionalProperties":false},"quoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["input","quoteFingerprint"],"additionalProperties":false}}}},"responses":{"201":{"description":"Scoped evidence and source metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceProjectId":{"type":"string"},"periodId":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"scope":{"type":"object","properties":{"includeSubdomains":{"type":"boolean"},"excludeInternal":{"type":"boolean"},"confirmRootScope":{"type":"boolean"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100},"target":{"type":"string"},"savedDomain":{"type":"string"},"normalizedFromWww":{"type":"boolean"}},"required":["includeSubdomains","excludeInternal","confirmRootScope","limit","target","savedDomain","normalizedFromWww"],"additionalProperties":false},"requestConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quoteFingerprint":{"type":"string"},"policyVersion":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"reservedRows":{"type":"number"},"consumedTasks":{"type":"number"},"consumedRows":{"type":"number"},"reservedBytes":{"type":"number"},"retainedBytes":{"type":"number"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"sentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"providerTaskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"records":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"url_from":{"type":"string","minLength":1,"maxLength":2048},"url_to":{"type":"string","minLength":1,"maxLength":2048},"first_seen":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"last_seen":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"is_lost":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"dofollow":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"item_type":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"anchor":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"attributes":{"anyOf":[{"maxItems":50,"type":"array","items":{"type":"string","maxLength":200}},{"type":"null"}]},"links_count":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["url_from","url_to"],"additionalProperties":false}},{"type":"null"}]},"totalAvailable":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","jobId","status","sentAt","receivedAt","providerTaskId","providerStatusCode","billing","failure","responseHash","records","totalAvailable","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["id","orgId","projectId","projectOrgId","sourceProjectId","periodId","createdBy","scope","requestConfig","quoteFingerprint","policyVersion","status","reservationStatus","reservedRows","consumedTasks","consumedRows","reservedBytes","retainedBytes","createdAt","updatedAt","example","attempt"],"additionalProperties":false},{"type":"null"}]},"quota":{"type":"object","properties":{"period":{"type":"string"},"tasks":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","tasks","rows"],"additionalProperties":false}},"required":["research"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/backlinks/preview":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Preview domain scope and allowance","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"includeSubdomains":{"type":"boolean"},"excludeInternal":{"type":"boolean"},"confirmRootScope":{"type":"boolean"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100}},"required":["includeSubdomains","excludeInternal","confirmRootScope","limit"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped evidence and source metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"preview":{"type":"object","properties":{"scope":{"type":"object","properties":{"includeSubdomains":{"type":"boolean"},"excludeInternal":{"type":"boolean"},"confirmRootScope":{"type":"boolean"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100},"target":{"type":"string"},"savedDomain":{"type":"string"},"normalizedFromWww":{"type":"boolean"}},"required":["includeSubdomains","excludeInternal","confirmRootScope","limit","target","savedDomain","normalizedFromWww"],"additionalProperties":false},"fingerprint":{"type":"string"},"quota":{"type":"object","properties":{"period":{"type":"string"},"tasks":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","tasks","rows"],"additionalProperties":false},"storage":{"type":"object","properties":{"orgUsedOrHeldBytes":{"type":"number"},"orgLimitBytes":{"type":"number"},"deploymentLimitBytes":{"type":"number"},"reservationBytes":{"type":"number"}},"required":["orgUsedOrHeldBytes","orgLimitBytes","deploymentLimitBytes","reservationBytes"],"additionalProperties":false},"allowed":{"type":"boolean"},"reason":{"anyOf":[{"type":"string","enum":["scope_confirmation","research_allowance","storage_limit"]},{"type":"null"}]},"plannedTasks":{"type":"number","const":1},"maximumRows":{"type":"number"},"remainingAfter":{"type":"object","properties":{"tasks":{"type":"number"},"rows":{"type":"number"}},"required":["tasks","rows"],"additionalProperties":false},"source":{"type":"object","properties":{"provider":{"type":"string","const":"dataforseo"},"collectionMethod":{"type":"string","const":"vendor_api"},"coverage":{"type":"string"}},"required":["provider","collectionMethod","coverage"],"additionalProperties":false}},"required":["scope","fingerprint","quota","storage","allowed","reason","plannedTasks","maximumRows","remainingAfter","source"],"additionalProperties":false}},"required":["preview"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/backlinks/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read scoped index snapshots","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped evidence and source metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceProjectId":{"type":"string"},"periodId":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"scope":{"type":"object","properties":{"includeSubdomains":{"type":"boolean"},"excludeInternal":{"type":"boolean"},"confirmRootScope":{"type":"boolean"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100},"target":{"type":"string"},"savedDomain":{"type":"string"},"normalizedFromWww":{"type":"boolean"}},"required":["includeSubdomains","excludeInternal","confirmRootScope","limit","target","savedDomain","normalizedFromWww"],"additionalProperties":false},"requestConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quoteFingerprint":{"type":"string"},"policyVersion":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"reservedRows":{"type":"number"},"consumedTasks":{"type":"number"},"consumedRows":{"type":"number"},"reservedBytes":{"type":"number"},"retainedBytes":{"type":"number"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"sentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"providerTaskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"records":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"url_from":{"type":"string","minLength":1,"maxLength":2048},"url_to":{"type":"string","minLength":1,"maxLength":2048},"first_seen":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"last_seen":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"is_lost":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"dofollow":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"item_type":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"anchor":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"attributes":{"anyOf":[{"maxItems":50,"type":"array","items":{"type":"string","maxLength":200}},{"type":"null"}]},"links_count":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["url_from","url_to"],"additionalProperties":false}},{"type":"null"}]},"totalAvailable":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","jobId","status","sentAt","receivedAt","providerTaskId","providerStatusCode","billing","failure","responseHash","records","totalAvailable","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["id","orgId","projectId","projectOrgId","sourceProjectId","periodId","createdBy","scope","requestConfig","quoteFingerprint","policyVersion","status","reservationStatus","reservedRows","consumedTasks","consumedRows","reservedBytes","retainedBytes","createdAt","updatedAt","example","attempt"],"additionalProperties":false}}},"required":["research"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/backlinks/{researchId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"researchId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read an index snapshot","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped evidence and source metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceProjectId":{"type":"string"},"periodId":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"scope":{"type":"object","properties":{"includeSubdomains":{"type":"boolean"},"excludeInternal":{"type":"boolean"},"confirmRootScope":{"type":"boolean"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100},"target":{"type":"string"},"savedDomain":{"type":"string"},"normalizedFromWww":{"type":"boolean"}},"required":["includeSubdomains","excludeInternal","confirmRootScope","limit","target","savedDomain","normalizedFromWww"],"additionalProperties":false},"requestConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quoteFingerprint":{"type":"string"},"policyVersion":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"reservedRows":{"type":"number"},"consumedTasks":{"type":"number"},"consumedRows":{"type":"number"},"reservedBytes":{"type":"number"},"retainedBytes":{"type":"number"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"sentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"providerTaskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"records":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"url_from":{"type":"string","minLength":1,"maxLength":2048},"url_to":{"type":"string","minLength":1,"maxLength":2048},"first_seen":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"last_seen":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"is_lost":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"dofollow":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"item_type":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"anchor":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"attributes":{"anyOf":[{"maxItems":50,"type":"array","items":{"type":"string","maxLength":200}},{"type":"null"}]},"links_count":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["url_from","url_to"],"additionalProperties":false}},{"type":"null"}]},"totalAvailable":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","jobId","status","sentAt","receivedAt","providerTaskId","providerStatusCode","billing","failure","responseHash","records","totalAvailable","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["id","orgId","projectId","projectOrgId","sourceProjectId","periodId","createdBy","scope","requestConfig","quoteFingerprint","policyVersion","status","reservationStatus","reservedRows","consumedTasks","consumedRows","reservedBytes","retainedBytes","createdAt","updatedAt","example","attempt"],"additionalProperties":false},{"type":"null"}]},"quota":{"type":"object","properties":{"period":{"type":"string"},"tasks":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","tasks","rows"],"additionalProperties":false}},"required":["research"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/backlinks/{researchId}/evidence":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"researchId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read retained vendor receipt","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped evidence and source metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"evidence":{"type":"object","properties":{"rawResponse":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["rawResponse","responseHash","receivedAt","example"],"additionalProperties":false}},"required":["evidence"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/backlinks/{researchId}/reconcile":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"researchId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Reconcile without another provider call","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped evidence and source metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceProjectId":{"type":"string"},"periodId":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"scope":{"type":"object","properties":{"includeSubdomains":{"type":"boolean"},"excludeInternal":{"type":"boolean"},"confirmRootScope":{"type":"boolean"},"limit":{"default":100,"type":"integer","minimum":1,"maximum":100},"target":{"type":"string"},"savedDomain":{"type":"string"},"normalizedFromWww":{"type":"boolean"}},"required":["includeSubdomains","excludeInternal","confirmRootScope","limit","target","savedDomain","normalizedFromWww"],"additionalProperties":false},"requestConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quoteFingerprint":{"type":"string"},"policyVersion":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"reservedRows":{"type":"number"},"consumedTasks":{"type":"number"},"consumedRows":{"type":"number"},"reservedBytes":{"type":"number"},"retainedBytes":{"type":"number"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"sentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"providerTaskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"records":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"url_from":{"type":"string","minLength":1,"maxLength":2048},"url_to":{"type":"string","minLength":1,"maxLength":2048},"first_seen":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"last_seen":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"is_lost":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"dofollow":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"item_type":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"anchor":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"attributes":{"anyOf":[{"maxItems":50,"type":"array","items":{"type":"string","maxLength":200}},{"type":"null"}]},"links_count":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["url_from","url_to"],"additionalProperties":false}},{"type":"null"}]},"totalAvailable":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","jobId","status","sentAt","receivedAt","providerTaskId","providerStatusCode","billing","failure","responseHash","records","totalAvailable","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["id","orgId","projectId","projectOrgId","sourceProjectId","periodId","createdBy","scope","requestConfig","quoteFingerprint","policyVersion","status","reservationStatus","reservedRows","consumedTasks","consumedRows","reservedBytes","retainedBytes","createdAt","updatedAt","example","attempt"],"additionalProperties":false},{"type":"null"}]},"quota":{"type":"object","properties":{"period":{"type":"string"},"tasks":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","tasks","rows"],"additionalProperties":false}},"required":["research"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/backlinks/checks":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List individual page checks","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped evidence and source metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceProjectId":{"type":"string"},"jobId":{"type":"string"},"sourceRecordIndex":{"type":"number"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"type":"string"},"targetUrl":{"type":"string"},"status":{"type":"string","enum":["prepared","running","completed","unknown"]},"reservedBytes":{"type":"number"},"retainedBytes":{"type":"number"},"receipt":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["observed","not_observed","unknown"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"type":"string"},"targetUrl":{"type":"string"},"fetchedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"httpStatus":{"anyOf":[{"type":"number"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseBytes":{"anyOf":[{"type":"number"},{"type":"null"}]},"matches":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string"},"text":{"type":"string"},"rel":{"type":"string"}},"required":["href","text","rel"],"additionalProperties":false}},"complete":{"type":"boolean"},"method":{"type":"string","const":"http"}},"required":["status","reason","sourceUrl","targetUrl","fetchedAt","httpStatus","responseHash","responseBytes","matches","complete","method"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","orgId","projectId","projectOrgId","sourceProjectId","jobId","sourceRecordIndex","createdBy","sourceUrl","targetUrl","status","reservedBytes","retainedBytes","receipt","createdAt","updatedAt"],"additionalProperties":false}}},"required":["checks"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Inspect one indexed page","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"researchId":{"type":"string","minLength":1},"recordIndex":{"type":"integer","minimum":0,"maximum":99}},"required":["researchId","recordIndex"],"additionalProperties":false}}}},"responses":{"201":{"description":"Scoped evidence and source metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"check":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceProjectId":{"type":"string"},"jobId":{"type":"string"},"sourceRecordIndex":{"type":"number"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"type":"string"},"targetUrl":{"type":"string"},"status":{"type":"string","enum":["prepared","running","completed","unknown"]},"reservedBytes":{"type":"number"},"retainedBytes":{"type":"number"},"receipt":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["observed","not_observed","unknown"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"type":"string"},"targetUrl":{"type":"string"},"fetchedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"httpStatus":{"anyOf":[{"type":"number"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseBytes":{"anyOf":[{"type":"number"},{"type":"null"}]},"matches":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string"},"text":{"type":"string"},"rel":{"type":"string"}},"required":["href","text","rel"],"additionalProperties":false}},"complete":{"type":"boolean"},"method":{"type":"string","const":"http"}},"required":["status","reason","sourceUrl","targetUrl","fetchedAt","httpStatus","responseHash","responseBytes","matches","complete","method"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","orgId","projectId","projectOrgId","sourceProjectId","jobId","sourceRecordIndex","createdBy","sourceUrl","targetUrl","status","reservedBytes","retainedBytes","receipt","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["check"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/backlinks/checks/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read scoped page checks","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped evidence and source metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceProjectId":{"type":"string"},"jobId":{"type":"string"},"sourceRecordIndex":{"type":"number"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"type":"string"},"targetUrl":{"type":"string"},"status":{"type":"string","enum":["prepared","running","completed","unknown"]},"reservedBytes":{"type":"number"},"retainedBytes":{"type":"number"},"receipt":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["observed","not_observed","unknown"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"type":"string"},"targetUrl":{"type":"string"},"fetchedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"httpStatus":{"anyOf":[{"type":"number"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseBytes":{"anyOf":[{"type":"number"},{"type":"null"}]},"matches":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string"},"text":{"type":"string"},"rel":{"type":"string"}},"required":["href","text","rel"],"additionalProperties":false}},"complete":{"type":"boolean"},"method":{"type":"string","const":"http"}},"required":["status","reason","sourceUrl","targetUrl","fetchedAt","httpStatus","responseHash","responseBytes","matches","complete","method"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","orgId","projectId","projectOrgId","sourceProjectId","jobId","sourceRecordIndex","createdBy","sourceUrl","targetUrl","status","reservedBytes","retainedBytes","receipt","createdAt","updatedAt"],"additionalProperties":false}}},"required":["checks"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/backlinks/checks/{checkId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"checkId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read an individual page check","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped evidence and source metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"check":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceProjectId":{"type":"string"},"jobId":{"type":"string"},"sourceRecordIndex":{"type":"number"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"type":"string"},"targetUrl":{"type":"string"},"status":{"type":"string","enum":["prepared","running","completed","unknown"]},"reservedBytes":{"type":"number"},"retainedBytes":{"type":"number"},"receipt":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["observed","not_observed","unknown"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"type":"string"},"targetUrl":{"type":"string"},"fetchedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"httpStatus":{"anyOf":[{"type":"number"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseBytes":{"anyOf":[{"type":"number"},{"type":"null"}]},"matches":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string"},"text":{"type":"string"},"rel":{"type":"string"}},"required":["href","text","rel"],"additionalProperties":false}},"complete":{"type":"boolean"},"method":{"type":"string","const":"http"}},"required":["status","reason","sourceUrl","targetUrl","fetchedAt","httpStatus","responseHash","responseBytes","matches","complete","method"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","orgId","projectId","projectOrgId","sourceProjectId","jobId","sourceRecordIndex","createdBy","sourceUrl","targetUrl","status","reservedBytes","retainedBytes","receipt","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["check"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a confirmed terminal page check","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"confirmCheckId":{"type":"string","minLength":1}},"required":["confirmCheckId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped evidence and source metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"deletedCheckId":{"type":"string"}},"required":["deletedCheckId"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/backlinks/checks/{checkId}/reconcile":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"checkId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Reconcile a stale check without fetching again","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped evidence and source metadata","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"check":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceProjectId":{"type":"string"},"jobId":{"type":"string"},"sourceRecordIndex":{"type":"number"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"type":"string"},"targetUrl":{"type":"string"},"status":{"type":"string","enum":["prepared","running","completed","unknown"]},"reservedBytes":{"type":"number"},"retainedBytes":{"type":"number"},"receipt":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["observed","not_observed","unknown"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"sourceUrl":{"type":"string"},"targetUrl":{"type":"string"},"fetchedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"httpStatus":{"anyOf":[{"type":"number"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseBytes":{"anyOf":[{"type":"number"},{"type":"null"}]},"matches":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string"},"text":{"type":"string"},"rel":{"type":"string"}},"required":["href","text","rel"],"additionalProperties":false}},"complete":{"type":"boolean"},"method":{"type":"string","const":"http"}},"required":["status","reason","sourceUrl","targetUrl","fetchedAt","httpStatus","responseHash","responseBytes","matches","complete","method"],"additionalProperties":false},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","orgId","projectId","projectOrgId","sourceProjectId","jobId","sourceRecordIndex","createdBy","sourceUrl","targetUrl","status","reservedBytes","retainedBytes","receipt","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["check"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/workspace/members":{"get":{"summary":"List workspace members and your role (session only)","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/workspace/members/{userId}":{"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Change a member's role (session only; owners and admins, admin and owner changes owner-only)","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"role":{"type":"string","enum":["owner","admin","member"]}},"required":["role"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Remove a member, revoking the API keys and pending invites they created; workspace connections they set up stay (session only)","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/workspace/invites":{"get":{"summary":"List workspace invites without links (session only; owners and admins)","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create one expiring single-use invite link, returned once (session only)","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"role":{"default":"member","type":"string","enum":["owner","admin","member"]},"label":{"type":"string","minLength":1,"maxLength":120}},"required":["role"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"description":"Nothing is emailed. Invites expire after 7 days."}},"/api/v1/workspace/invites/batch":{"post":{"summary":"Create up to 10 invite links, returned once (session only)","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"invites":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"role":{"default":"member","type":"string","enum":["owner","admin","member"]},"label":{"type":"string","minLength":1,"maxLength":120}},"required":["role"],"additionalProperties":false}}},"required":["invites"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/workspace/invites/accept":{"post":{"summary":"Join a workspace with an invite token (session only; an existing member is unchanged)","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"token":{"type":"string","minLength":1,"maxLength":200}},"required":["token"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"410":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/workspace/plan-keep":{"post":{"summary":"Choose which websites or questions stay scanned while over the plan's limit","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"resource":{"type":"string","enum":["websites","prompts"]},"keep":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"pause":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["resource","keep","pause"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"description":"After a downgrade the newest websites and active questions above the plan's limit are paused (planPaused in project lists and summaries); nothing is deleted. Name paused ids to keep and the same number of kept ids to pause, so the limit is never exceeded. Questions are pooled across the workspace. Returns pausedIds after the swap. 409 conflict when an id to keep is not paused or an id to pause is not kept; 409 nothing_paused when nothing is over the limit. An upgrade un-pauses on its own. Starts no scan."}},"/api/v1/workspace/invites/{inviteId}":{"parameters":[{"name":"inviteId","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Revoke an invite (session only; owners and admins)","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List manual content documents","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Manual content result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","required":["id","plannedDate","planRevision"],"properties":{"id":{"type":"string"},"plannedDate":{"type":["string","null"],"format":"date","description":"A UTC editorial calendar day, not a publication or scheduled job."},"planRevision":{"type":"integer","minimum":0}},"additionalProperties":true}}},"additionalProperties":true}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a manual document","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"brief":{"type":"string","maxLength":4000}},"required":["title"],"additionalProperties":false}}}},"responses":{"201":{"description":"Manual content result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read scoped documents by id","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Manual content result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","required":["id","plannedDate","planRevision"],"properties":{"id":{"type":"string"},"plannedDate":{"type":["string","null"],"format":"date","description":"A UTC editorial calendar day, not a publication or scheduled job."},"planRevision":{"type":"integer","minimum":0}},"additionalProperties":true}}},"additionalProperties":true}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/sources":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List eligible saved sources; no crawl","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Manual content result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read content and review history","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Manual content result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"document":{"type":"object","required":["id","plannedDate","planRevision"],"properties":{"id":{"type":"string"},"plannedDate":{"type":["string","null"],"format":"date","description":"A UTC editorial calendar day, not a publication or scheduled job."},"planRevision":{"type":"integer","minimum":0}},"additionalProperties":true}},"additionalProperties":true}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Save a revision and invalidate its current review","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"title":{"type":"string","minLength":1,"maxLength":200},"brief":{"type":"string","maxLength":4000},"draft":{"type":"string"},"sources":{"maxItems":5,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["audit","keyword","answer","cluster","onboarding"]},"id":{"type":"string","minLength":1,"maxLength":200}},"required":["kind","id"],"additionalProperties":false}}},"required":["expectedRevision","title","brief","draft","sources"],"additionalProperties":false}}}},"responses":{"200":{"description":"Manual content result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a document and its review history","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Manual content result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/plan":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"put":{"summary":"Set or clear a date-only UTC editorial plan; does not publish or schedule work","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedPlanRevision":{"type":"integer","minimum":0,"maximum":2147483647},"plannedDate":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]}},"required":["expectedPlanRevision","plannedDate"],"additionalProperties":false}}}},"responses":{"200":{"description":"Manual content result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"document":{"type":"object","required":["id","plannedDate","planRevision"],"properties":{"id":{"type":"string"},"plannedDate":{"type":["string","null"],"format":"date","description":"A UTC editorial calendar day, not a publication or scheduled job."},"planRevision":{"type":"integer","minimum":0}},"additionalProperties":true}},"additionalProperties":true}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/attach-cluster":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Attach selected real-origin group evidence at exact revisions","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"clusterId":{"type":"string","minLength":1,"maxLength":200},"clusterRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"memberIds":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["expectedRevision","clusterId","clusterRevision","memberIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Manual content result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/approve":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Record an explicit review for a revision","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Manual content result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/export":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","required":true,"schema":{"type":"string","enum":["markdown","text","html","prompt"]}}],"get":{"summary":"Read text for export (markdown or text as saved; html or a copy-as-prompt rendered from it) without publishing/updating; external publication status is separate","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Manual content result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"published":{"type":"boolean","enum":[false],"deprecated":true,"description":"Legacy export-action flag: this export performs no publication. It is not the document's external WordPress status."},"publicationScope":{"type":"string","enum":["export_action_only"]},"externalPublicationStatus":{"type":"string","enum":["not_evaluated"]},"publicationReceiptsPath":{"type":"string","description":"Scoped read-only path for saved WordPress delivery/observation receipts."}},"additionalProperties":true}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/organize":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List content tags, folders and each document's folder and tags","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/organize/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Tag, untag and move up to 50 documents, all or none","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"addTagIds":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"removeTagIds":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"folderId":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}]},"documentId":{"type":"string","minLength":1,"maxLength":64}},"required":["documentId"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/tags":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create a tag","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"color":{"type":"string","enum":["amber","green","blue","rose","violet","teal","orange","fuchsia"]}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/tags/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create up to 20 tags, all or none","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"color":{"type":"string","enum":["amber","green","blue","rose","violet","teal","orange","fuchsia"]}},"required":["name"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"responses":{"201":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/tags/{tagId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"tagId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Rename a tag or change its color","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"color":{"type":"string","enum":["amber","green","blue","rose","violet","teal","orange","fuchsia"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a tag and remove it from documents","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/folders":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create a folder","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/folders/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create up to 20 folders, all or none","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40}},"required":["name"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"responses":{"201":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/folders/{folderId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"folderId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Rename a folder","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a folder; its documents move to the top level","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/organize":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"put":{"summary":"Add or remove tags and move a document to a folder","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"addTagIds":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"removeTagIds":{"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"folderId":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/improvements":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List saved page improvements","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped manual text patch result; no network or provider call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create a user-authored patch from exact saved audit blocks","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"auditId":{"type":"string","minLength":1,"maxLength":200},"pageUrl":{"type":"string","maxLength":2048,"format":"uri"},"title":{"type":"string","minLength":1,"maxLength":200},"blockIds":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}}},"required":["auditId","pageUrl","title","blockIds"],"additionalProperties":false}}}},"responses":{"201":{"description":"Scoped manual text patch result; no network or provider call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/improvements/sources":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"auditId","in":"query","required":false,"schema":{"type":"string"}},{"name":"pageUrl","in":"query","required":false,"schema":{"type":"string","format":"uri"}}],"get":{"summary":"List bounded static-text artifacts from explicit saved audits, plus the requested capture when auditId and pageUrl are given; no crawl","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped manual text patch result; no network or provider call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/improvements/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read up to20 scoped improvements by ID","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped manual text patch result; no network or provider call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/improvements/{improvementId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"improvementId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read original text, proposals and finalized receipt","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped manual text patch result; no network or provider call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"summary":"Save user-written proposals and review decisions with revision checking","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"hunks":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"blockId":{"type":"string","minLength":1,"maxLength":100},"after":{"type":"string","maxLength":4096},"reason":{"type":"string","maxLength":500},"evidenceBlockIds":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}},"decision":{"type":"string","enum":["pending","accepted","rejected"]}},"required":["blockId","after","reason","evidenceBlockIds","decision"],"additionalProperties":false}}},"required":["expectedRevision","hunks"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped manual text patch result; no network or provider call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/improvements/{improvementId}/finalize":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"improvementId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Freeze one immutable reviewed manual text patch; not publication","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped manual text patch result; no network or provider call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/improvements/{improvementId}/export":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"improvementId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read finalized text patch and JSON receipt; not executable HTML or a CMS patch","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped manual text patch result; no network or provider call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/prompts/{promptId}/labels":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"promptId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Save current question labels without changing answers or scan settings","description":"Exact-value compare-and-save. Null means unknown, empty topic means explicitly no topic, and false means unbranded. Read saved labels from the existing project summary or batch. These are current classifications, not historical answer metadata.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedLabels":{"type":"object","properties":{"topic":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"branded":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["topic","branded"],"additionalProperties":false},"labels":{"type":"object","properties":{"topic":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"branded":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["topic","branded"],"additionalProperties":false}},"required":["expectedLabels","labels"],"additionalProperties":false}}}},"responses":{"200":{"description":"Saved current labels; no supplier or answer units","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/responses":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"engine","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","enum":["chatgpt","perplexity","gemini","claude","copilot","google_aio","grok","deepseek"]}},{"name":"range","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","enum":["all","today","7d","14d","28d","30d","90d","custom"]}},{"name":"from","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"verdict","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","enum":["all","named","cited","retrieved"]}},{"name":"topic","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string"}},{"name":"branded","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","enum":["all","unknown","branded","unbranded"]}},{"name":"status","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","enum":["all","active","inactive"]}},{"name":"query","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","minLength":1,"maxLength":200}},{"name":"sort","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","enum":["newest","oldest","sources","position"]}},{"name":"offset","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},{"name":"limit","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"integer","minimum":1,"maximum":100}}],"get":{"summary":"List a bounded page of saved responses with complete filtered totals","description":"Current topic, branded and active labels compose with engine, verdict, date, full saved-answer search and sort. Recorded question wording remains receipt evidence.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Response history","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectResponsesData"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Read unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/responses/batch":{"post":{"summary":"Read response totals and up to five receipts for 20 projects","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"engine":{"type":"string","enum":["chatgpt","perplexity","gemini","claude","copilot","google_aio","grok","deepseek"]},"range":{"type":"string","enum":["all","today","7d","14d","28d","30d","90d","custom"]},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"verdict":{"type":"string","enum":["all","named","cited","retrieved"]},"topic":{"type":"string"},"branded":{"type":"string","enum":["all","unknown","branded","unbranded"]},"status":{"type":"string","enum":["all","active","inactive"]},"query":{"type":"string","minLength":1,"maxLength":200},"sort":{"type":"string","enum":["newest","oldest","sources","position"]},"projectIds":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"uniqueItems":true}},"required":["projectIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Bounded project response histories","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectResponsesBatchData"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Read unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/prompts/{promptId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"promptId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"patch":{"summary":"Edit or activate a tracked question for future scans","description":"Exact-value compare-and-save. Saved response receipts and queued jobs retain their recorded question text. Configuration changes invalidate recurring consent and never start a scan.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expected":{"type":"object","properties":{"text":{"type":"string","minLength":1},"isActive":{"type":"boolean"}},"required":["text","isActive"],"additionalProperties":false},"prompt":{"type":"object","properties":{"text":{"type":"string","minLength":1},"isActive":{"type":"boolean"}},"required":["text","isActive"],"additionalProperties":false}},"required":["expected","prompt"],"additionalProperties":false}}}},"responses":{"200":{"description":"Question updated or unchanged","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PromptLifecycleData"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Question not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Expected state changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Write unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Delete a tracked question while keeping its saved answers","description":"Soft delete: the question stops being scanned and disappears from lists, counts and exports. Saved answers stay stored as evidence and nothing is physically removed. Deleting an already deleted question succeeds with outcome already_deleted. Deleting an active question invalidates recurring consent and no scan starts.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Question deleted or already deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PromptDeleteData"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Question not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid question ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Write unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/prompts/status/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Activate or deactivate up to 50 tracked questions","description":"Each item carries the status the caller last saw. Results are per item: updated, unchanged, conflict or not_found; a conflict never blocks the rest. Question IDs must be unique. Any changed status invalidates recurring consent and no scan starts.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"promptId":{"type":"string","minLength":1,"maxLength":200},"expectedIsActive":{"type":"boolean"},"isActive":{"type":"boolean"}},"required":["promptId","expectedIsActive","isActive"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"responses":{"200":{"description":"Per-question results","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PromptStatusBatchData"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Write unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/prompts/delete/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Delete up to 50 tracked questions while keeping their saved answers","description":"Soft delete. Results are per item: deleted, already_deleted or not_found; one unknown question never blocks the rest. Question IDs must be unique. Saved answers stay stored as evidence. Deleting an active question invalidates recurring consent and no scan starts.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"promptIds":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["promptIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Per-question results","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PromptDeleteBatchData"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Write unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/prompts/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Track up to 50 questions without starting a scan","description":"Questions already tracked in the project (same text, ignoring case and surrounding space) are skipped and reported as duplicate; the rest are created in one transaction. Uses no answer allowance, starts no scan and invalidates recurring consent when anything is created.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"texts":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":2000}},"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000},"topic":{"type":"string","maxLength":200}},"required":["text"],"additionalProperties":false}}},"additionalProperties":false}}}},"responses":{"201":{"description":"Per-question results","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PromptCreateBatchData"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Session changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Write unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/prompts/export":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"engine","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","enum":["chatgpt","perplexity","gemini","claude","copilot","google_aio","grok","deepseek"]}},{"name":"range","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","enum":["all","today","7d","14d","28d","30d","90d","custom"]}},{"name":"from","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"topic","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string"}},{"name":"branded","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","enum":["all","unknown","branded","unbranded"]}},{"name":"status","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","enum":["all","active","inactive"]}},{"name":"query","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","maxLength":200}},{"name":"brand","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","minLength":1,"maxLength":200}},{"name":"sort","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","enum":["prompt","runs","last","visibility","position","created","volume","mentions"]}},{"name":"direction","in":"query","required":false,"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"string","enum":["asc","desc"]}}],"get":{"summary":"Export the filtered prompt table as CSV text","description":"One row per prompt across every page, using the dashboard's filters, sort and numbers. Includes position, sentiment, visibility, competitors, and a verdict and collection_method column per engine. Unknown values are explicit markers (not measured, not collected, unavailable), never zero. Text cells beginning with = + - or @ are prefixed with an apostrophe. No provider request is made.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"CSV export","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PromptExportData"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Invalid filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Read unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/search-console/connections/batch":{"post":{"summary":"Read selected connection status for up to 50 accessible projects; no Google calls","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped Search Console response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectIds"],"properties":{"projectIds":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}}}}}}}}},"/api/v1/projects/{projectId}/search-console/revocations/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read up to 50 pending removals for an organization administrator; no Google calls","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped Search Console response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}}}}}}}}},"/api/v1/integrations/gsc/callback":{"get":{"summary":"Complete a browser-bound Google authorization and redirect without exposing tokens","security":[{"sessionAuth":[]}],"responses":{"303":{"description":"Return to property selection or recovery"}}}},"/api/v1/projects/{projectId}/search-console":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read project Search Console status","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped Search Console response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/search-console/report":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read one bounded finalized Web performance view","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"view","in":"query","required":true,"schema":{"type":"string","enum":["overview","daily","queries","pages"]}},{"name":"startDate","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"compare","in":"query","required":false,"description":"1 also returns the previous equal-length period as previous.","schema":{"type":"string","enum":["1","true"]}}],"responses":{"200":{"description":"Scoped Search Console response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/search-console/handoff":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Get a browser handoff for a person to connect","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped Search Console response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/search-console/start":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Start a browser-bound Google consent flow","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Scoped Search Console response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/search-console/disconnect":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Disconnect this project and request last-grant revocation","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Scoped Search Console response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/search-console/selection/{selectionId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"selectionId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List matching properties in the initiating browser","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped Search Console response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}},"post":{"summary":"Choose a matching property","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Scoped Search Console response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/search-console/revocations":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List pending Google access removal for organization administrators","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped Search Console response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/search-console/revocations/{grantId}/forget":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"grantId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Remove an unconfirmed local credential without claiming Google revocation","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Scoped Search Console response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/search-console/revocations/{grantId}/retry":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"grantId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Retry unconfirmed Google access removal","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Scoped Search Console response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/ga4/connections/batch":{"post":{"summary":"Read selected connection status for up to 50 accessible projects; no Google calls","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped Google Analytics response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectIds"],"properties":{"projectIds":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}}}}}}}}},"/api/v1/projects/{projectId}/ga4/revocations/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read up to 50 pending removals for an organization administrator; no Google calls","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped Google Analytics response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}}}}}}}}},"/api/v1/integrations/ga4/callback":{"get":{"summary":"Complete a browser-bound Google authorization and redirect without exposing tokens","security":[{"sessionAuth":[]}],"responses":{"303":{"description":"Return to property selection or recovery"}}}},"/api/v1/projects/{projectId}/ga4":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read project Google Analytics status","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped Google Analytics response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/ga4/report":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read one bounded AI-visits view: overview, daily, sources or landing pages, optionally with the previous equal period. Counts visits Google Analytics attributed to an AI tool; real numbers are likely higher","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"view","in":"query","required":true,"schema":{"type":"string","enum":["overview","daily","sources","landing_pages"]}},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","28d","90d"],"default":"28d"}},{"name":"previous","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Scoped Google Analytics response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/ga4/handoff":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Get a browser handoff for a person to connect","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped Google Analytics response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/ga4/start":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Start a browser-bound Google consent flow","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Scoped Google Analytics response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/ga4/disconnect":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Disconnect this project and request last-grant revocation","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Scoped Google Analytics response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/ga4/selection/{selectionId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"selectionId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List matching properties in the initiating browser","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped Google Analytics response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}},"post":{"summary":"Choose a matching property","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Scoped Google Analytics response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/ga4/revocations":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List pending Google access removal for organization administrators","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped Google Analytics response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/ga4/revocations/{grantId}/forget":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"grantId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Remove an unconfirmed local credential without claiming Google revocation","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Scoped Google Analytics response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/ga4/revocations/{grantId}/retry":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"grantId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Retry unconfirmed Google access removal","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Scoped Google Analytics response"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"409":{"description":"Connection changed"},"422":{"description":"Invalid input"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/traffic/pages":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read one row per page joining Google clicks, AI visits and AI citations by path","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","28d","90d"],"default":"28d"}},{"name":"filter","in":"query","required":false,"schema":{"type":"string","enum":["cited_no_ai_visits","google_never_cited","top_ai"]}}],"responses":{"200":{"description":"Per-page traffic and citation rows; sources that are not connected are null"},"401":{"description":"Authentication required"},"404":{"description":"Not found or inaccessible"},"422":{"description":"Invalid input or filter needs an unconnected source"},"429":{"description":"Rate limited"},"503":{"description":"Unavailable"}}}},"/api/v1/projects/{projectId}/content/{documentId}/drafts":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List draft attempts","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Draft attempt result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Confirm an unchanged quote and send one bounded draft request","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"quoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["expectedRevision","quoteFingerprint"],"additionalProperties":false}}}},"responses":{"201":{"description":"Draft attempt result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/drafts/preview":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Preview scope and allowance","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Draft attempt result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/drafts/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read scoped draft attempts","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Draft attempt result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/drafts/{attemptId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"attemptId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read a draft attempt and candidate","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Draft attempt result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/drafts/{attemptId}/evidence":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"attemptId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read retained raw evidence","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Draft attempt result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/drafts/{attemptId}/reconcile":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"attemptId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Reconcile without another provider request","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Draft attempt result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/drafts/{attemptId}/apply":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"attemptId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a candidate with revision checking","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Draft attempt result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/attachments":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Store one file for a content turn: images (PNG, JPEG, WebP) or documents (PDF, TXT, MD), up to 5 MB","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"contentBase64":{"type":"string","minLength":1,"maxLength":6990516}},"required":["name","contentBase64"],"additionalProperties":false}}}},"responses":{"201":{"description":"Stored attachment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"415":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/turns/preview":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Quote an exact instruction and saved document without spending","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"instruction":{"type":"string","minLength":1},"format":{"anyOf":[{"type":"string","enum":["Comparison","Article","Answer block","FAQ","Landing section"]},{"type":"null"}]},"mode":{"type":"string","enum":["write","plan"]},"attachmentIds":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"searchConsole":{"type":"boolean"},"documentId":{"type":"string","minLength":1,"maxLength":200},"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["instruction"],"additionalProperties":false}}}},"responses":{"200":{"description":"Content turn result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/turns":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Admit one quoted turn","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"instruction":{"type":"string","minLength":1},"format":{"anyOf":[{"type":"string","enum":["Comparison","Article","Answer block","FAQ","Landing section"]},{"type":"null"}]},"mode":{"type":"string","enum":["write","plan"]},"attachmentIds":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}},"searchConsole":{"type":"boolean"},"documentId":{"type":"string","minLength":1,"maxLength":200},"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"turnId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"quoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["instruction","turnId","quoteFingerprint"],"additionalProperties":false}}}},"responses":{"202":{"description":"Content turn result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/turns/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read turns by client ID","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Content turn result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/turns/{turnId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"turnId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Read turn and streaming progress","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Content turn result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/turns/{turnId}/steps":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"turnId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Read the real steps of one turn","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Content turn result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/turns/steps/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read the real steps of up to fifty turns","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"maxItems":50,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Content turn result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/turns/{turnId}/finalize":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"turnId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Finalize a saved candidate without a provider call","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Content turn result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/turns/{turnId}/respond":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"turnId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Answer the plan question, skip it, or ask for plan changes","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"answer"},"optionId":{"type":"string","pattern":"^[123]$"}},"required":["type","optionId"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"skip"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"revise"},"feedback":{"type":"string","minLength":1,"maxLength":800}},"required":["type","feedback"],"additionalProperties":false}]}}}},"responses":{"202":{"description":"Content turn result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/turns/{turnId}/approve":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"turnId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Approve a plan so writing starts with the same writing try","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"202":{"description":"Content turn result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/turns/{turnId}/abandon":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"turnId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Discard an unapproved plan and release its writing try","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Content turn result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/article-state":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read the compact saved state of a document","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Content turn result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/turns":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read a document conversation","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Content turn result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/improvements/{improvementId}/proposals":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"improvementId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List page proposal attempts","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Page proposal result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Confirm one bounded proposal request","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"guidance":{"type":"string","minLength":1,"maxLength":2000},"fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["expectedRevision","guidance","fingerprint"],"additionalProperties":false}}}},"responses":{"201":{"description":"Page proposal result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/improvements/{improvementId}/proposals/preview":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"improvementId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Preview captured blocks, model and allowance","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"guidance":{"type":"string","minLength":1,"maxLength":2000}},"required":["expectedRevision","guidance"],"additionalProperties":false}}}},"responses":{"200":{"description":"Page proposal result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/improvements/{improvementId}/proposals/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"improvementId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read scoped proposal attempts","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Page proposal result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/improvements/{improvementId}/proposals/{attemptId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"improvementId","in":"path","required":true,"schema":{"type":"string"}},{"name":"attemptId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read one proposal attempt","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Page proposal result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/improvements/{improvementId}/proposals/{attemptId}/evidence":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"improvementId","in":"path","required":true,"schema":{"type":"string"}},{"name":"attemptId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read retained response evidence","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Page proposal result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/improvements/{improvementId}/proposals/{attemptId}/reconcile":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"improvementId","in":"path","required":true,"schema":{"type":"string"}},{"name":"attemptId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Reconcile without resending","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Page proposal result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/improvements/{improvementId}/proposals/{attemptId}/apply":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"improvementId","in":"path","required":true,"schema":{"type":"string"}},{"name":"attemptId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply candidate to pending review with revision checking","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["expectedRevision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Page proposal result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/wordpress":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read WordPress metadata without credentials","description":"Project-scoped WordPress new-post path. Only current owners/admins may change connections, create or verify delivery. One creation per document/canonical configured destination survives reconnects and live-parent deletion. Unconfirmed delivery is never resent. No automatic proof, indexing or scheduled publishing. Existing content updates replace the complete title and body; a pre-save check cannot prevent another writer saving before the update.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped connection, preview or retained receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Check and seal a project-bound application password","description":"Project-scoped WordPress new-post path. Only current owners/admins may change connections, create or verify delivery. One creation per document/canonical configured destination survives reconnects and live-parent deletion. Unconfirmed delivery is never resent. No automatic proof, indexing or scheduled publishing. Existing content updates replace the complete title and body; a pre-save check cannot prevent another writer saving before the update.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"username":{"type":"string","minLength":1,"maxLength":128},"applicationPassword":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9 ]+$"},"siteUrl":{"type":"string","maxLength":512,"format":"uri"},"expectedVersion":{"type":"integer","minimum":0,"maximum":2147483646}},"required":["username","applicationPassword","siteUrl","expectedVersion"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped connection, preview or retained receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"201":{"description":"New delivery receipt retained; inspect delivery and observation states, not a publication guarantee."},"400":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Forget sealed credentials while retaining receipts and unresolved guards","description":"Project-scoped WordPress new-post path. Only current owners/admins may change connections, create or verify delivery. One creation per document/canonical configured destination survives reconnects and live-parent deletion. Unconfirmed delivery is never resent. No automatic proof, indexing or scheduled publishing. Existing content updates replace the complete title and body; a pre-save check cannot prevent another writer saving before the update.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedVersion":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647}},"required":["expectedVersion"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped connection, preview or retained receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"201":{"description":"New delivery receipt retained; inspect delivery and observation states, not a publication guarantee."},"400":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/wordpress/preview":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Preview exact reviewed HTML, destination/state and receipt allowance without a network request","description":"Project-scoped WordPress new-post path. Only current owners/admins may change connections, create or verify delivery. One creation per document/canonical configured destination survives reconnects and live-parent deletion. Unconfirmed delivery is never resent. No automatic proof, indexing or scheduled publishing. Existing content updates replace the complete title and body; a pre-save check cannot prevent another writer saving before the update.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"expectedConnectionVersion":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"status":{"type":"string","enum":["draft","publish"]},"baseline":{"type":"object","properties":{"promptId":{"type":"string","minLength":1,"maxLength":200},"baselineRunIds":{"minItems":1,"maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["promptId","baselineRunIds"],"additionalProperties":false}},"required":["expectedRevision","expectedConnectionVersion","status"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped connection, preview or retained receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/wordpress":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Confirm one immutable new-post delivery, never automatically retried","description":"Project-scoped WordPress new-post path. Only current owners/admins may change connections, create or verify delivery. One creation per document/canonical configured destination survives reconnects and live-parent deletion. Unconfirmed delivery is never resent. No automatic proof, indexing or scheduled publishing. Existing content updates replace the complete title and body; a pre-save check cannot prevent another writer saving before the update.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"expectedConnectionVersion":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"status":{"type":"string","enum":["draft","publish"]},"baseline":{"type":"object","properties":{"promptId":{"type":"string","minLength":1,"maxLength":200},"baselineRunIds":{"minItems":1,"maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["promptId","baselineRunIds"],"additionalProperties":false},"fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"acknowledgeCreateOnce":{"type":"boolean","const":true}},"required":["expectedRevision","expectedConnectionVersion","status","fingerprint","acknowledgeCreateOnce"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped connection, preview or retained receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"201":{"description":"New delivery receipt retained; inspect delivery and observation states, not a publication guarantee."},"400":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/wordpress/update/preview":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Review the exact existing post or page and full replacement","description":"Requires current owner/admin write access. Reads raw content but does not write. Full title/body replacement removes existing block, shortcode and plugin markup. Native WordPress pre-save drift checking cannot prevent a later edit being overwritten.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"expectedConnectionVersion":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"baseline":{"type":"object","properties":{"promptId":{"type":"string","minLength":1,"maxLength":200},"baselineRunIds":{"minItems":1,"maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["promptId","baselineRunIds"],"additionalProperties":false},"status":{"type":"string","enum":["draft","publish"]},"resourceType":{"type":"string","enum":["post","page"]},"remoteId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["expectedRevision","expectedConnectionVersion","resourceType","remoteId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped connection, preview or retained receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/content/{documentId}/wordpress/update":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Confirm complete title/body replacement at an exact WordPress target","description":"Requires explicit full-replacement and overwrite-race consent. Checks the raw snapshot before one send; another writer can save between the check and mutation. An unknown outcome is never resent.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedRevision":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"expectedConnectionVersion":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"baseline":{"type":"object","properties":{"promptId":{"type":"string","minLength":1,"maxLength":200},"baselineRunIds":{"minItems":1,"maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["promptId","baselineRunIds"],"additionalProperties":false},"status":{"type":"string","enum":["draft","publish"]},"resourceType":{"type":"string","enum":["post","page"]},"remoteId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"expectedRemoteRevisionHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"acknowledgeFullReplacement":{"type":"boolean","const":true},"acknowledgeOverwriteRace":{"type":"boolean","const":true}},"required":["expectedRevision","expectedConnectionVersion","resourceType","remoteId","expectedRemoteRevisionHash","fingerprint","acknowledgeFullReplacement","acknowledgeOverwriteRace"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped connection, preview or retained receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"201":{"description":"New delivery receipt retained; inspect delivery and observation states, not a publication guarantee."},"400":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/wordpress/publications":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List up to 20 retained project delivery receipts","description":"Project-scoped WordPress new-post path. Only current owners/admins may change connections, create or verify delivery. One creation per document/canonical configured destination survives reconnects and live-parent deletion. Unconfirmed delivery is never resent. No automatic proof, indexing or scheduled publishing. Existing content updates replace the complete title and body; a pre-save check cannot prevent another writer saving before the update.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped connection, preview or retained receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/wordpress/publications/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read up to 20 requested scoped receipt summaries","description":"Project-scoped WordPress new-post path. Only current owners/admins may change connections, create or verify delivery. One creation per document/canonical configured destination survives reconnects and live-parent deletion. Unconfirmed delivery is never resent. No automatic proof, indexing or scheduled publishing. Existing content updates replace the complete title and body; a pre-save check cannot prevent another writer saving before the update.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped connection, preview or retained receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/wordpress/publications/{publicationId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"publicationId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read a frozen payload and acknowledgement/observation evidence","description":"Project-scoped WordPress new-post path. Only current owners/admins may change connections, create or verify delivery. One creation per document/canonical configured destination survives reconnects and live-parent deletion. Unconfirmed delivery is never resent. No automatic proof, indexing or scheduled publishing. Existing content updates replace the complete title and body; a pre-save check cannot prevent another writer saving before the update.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Scoped connection, preview or retained receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/wordpress/publications/{publicationId}/proof/preview":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"publicationId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Preview proof consent, current allowance and exact publication evidence without dispatch","description":"Requires project proof-write and quota-read authority. An acknowledgement time is not remote publication or indexing time; historical settings comparability is unverified.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped connection, preview or retained receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/wordpress/publications/{publicationId}/proof":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"publicationId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Confirm proof and three checkpoints with a reviewed quote","description":"Requires project proof-write and quota-read authority. Atomically links without dispatch, reservation or guarantee of future collection.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"acceptedAnswerCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"acceptedImmediateAnswerCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["fingerprint","acceptedAnswerCount","acceptedImmediateAnswerCount"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped connection, preview or retained receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"201":{"description":"New delivery receipt retained; inspect delivery and observation states, not a publication guarantee."},"400":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/wordpress/publications/{publicationId}/verify":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"publicationId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Reserve one of five known-ID checks and separately observe same-origin public markup without creating another post","description":"Project-scoped WordPress new-post path. Only current owners/admins may change connections, create or verify delivery. One creation per document/canonical configured destination survives reconnects and live-parent deletion. Unconfirmed delivery is never resent. No automatic proof, indexing or scheduled publishing. Existing content updates replace the complete title and body; a pre-save check cannot prevent another writer saving before the update.","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"expectedObservationCount":{"type":"integer","minimum":0,"maximum":4}},"required":["expectedObservationCount"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scoped connection, preview or retained receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"201":{"description":"New delivery receipt retained; inspect delivery and observation states, not a publication guarantee."},"400":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; unknown sends must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/indexed-mentions":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List indexed research and allowance","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Project-scoped indexed vendor research and provenance","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"type":"array","items":{"type":"object","properties":{"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"id":{"type":"string"},"scope":{"type":"object","properties":{"targetType":{"type":"string","enum":["keyword","domain"]},"target":{"type":"string","minLength":1,"maxLength":250},"platform":{"type":"string","enum":["google","chat_gpt"]},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":50,"type":"integer","minimum":1,"maximum":50}},"required":["targetType","target","platform","locationCode","languageCode","limit"],"additionalProperties":false},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["example","id","scope","status","reservationStatus","createdAt"],"additionalProperties":false}},"quota":{"type":"object","properties":{"period":{"type":"string"},"tasks":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","tasks","rows"],"additionalProperties":false}},"required":["research","quota"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Confirm a quote and acquire one indexed research task","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"input":{"type":"object","properties":{"targetType":{"type":"string","enum":["keyword","domain"]},"target":{"type":"string","minLength":1,"maxLength":250},"platform":{"type":"string","enum":["google","chat_gpt"]},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":50,"type":"integer","minimum":1,"maximum":50}},"required":["targetType","target","platform","locationCode","languageCode","limit"],"additionalProperties":false},"quoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["input","quoteFingerprint"],"additionalProperties":false}}}},"responses":{"201":{"description":"Project-scoped indexed vendor research and provenance","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"anyOf":[{"type":"object","properties":{"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"periodId":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"scope":{"type":"object","properties":{"targetType":{"type":"string","enum":["keyword","domain"]},"target":{"type":"string","minLength":1,"maxLength":250},"platform":{"type":"string","enum":["google","chat_gpt"]},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":50,"type":"integer","minimum":1,"maximum":50}},"required":["targetType","target","platform","locationCode","languageCode","limit"],"additionalProperties":false},"requestConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quoteFingerprint":{"type":"string"},"policyVersion":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"reservedRows":{"type":"number"},"consumedTasks":{"type":"number"},"consumedRows":{"type":"number"},"reservedBytes":{"type":"number"},"retainedBytes":{"type":"number"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"sentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"providerTaskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"records":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["google","chat_gpt"]},"model_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"location_code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"language_code":{"type":"string"},"question":{"type":"string","minLength":1},"answer":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_response_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_response_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_web_search_based":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"sources":{"anyOf":[{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},{"type":"null"}]},"search_results":{"anyOf":[{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},{"type":"null"}]},"ai_search_volume":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]}},"required":["platform","location_code","language_code","question"],"additionalProperties":false}},{"type":"null"}]},"totalAvailable":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","jobId","status","sentAt","receivedAt","providerTaskId","providerStatusCode","billing","failure","responseHash","records","totalAvailable","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["example","id","orgId","projectId","projectOrgId","periodId","createdBy","scope","requestConfig","quoteFingerprint","policyVersion","status","reservationStatus","reservedRows","consumedTasks","consumedRows","reservedBytes","retainedBytes","createdAt","updatedAt","attempt"],"additionalProperties":false},{"type":"null"}]},"quota":{"type":"object","properties":{"period":{"type":"string"},"tasks":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","tasks","rows"],"additionalProperties":false}},"required":["research"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/indexed-mentions/markets":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read free platform and market catalogue","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Project-scoped indexed vendor research and provenance","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"markets":{"type":"array","items":{"type":"object","properties":{"locationCode":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"languages":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"platforms":{"type":"array","items":{"type":"string","enum":["google","chat_gpt"]}},"responsesCount":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["code","name","platforms","responsesCount"],"additionalProperties":false}}},"required":["locationCode","name","languages"],"additionalProperties":false}},"acquiredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"source":{"type":"string","format":"uri"}},"required":["markets","acquiredAt","source"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/indexed-mentions/preview":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Preview indexed scope and allowance","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"targetType":{"type":"string","enum":["keyword","domain"]},"target":{"type":"string","minLength":1,"maxLength":250},"platform":{"type":"string","enum":["google","chat_gpt"]},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":50,"type":"integer","minimum":1,"maximum":50}},"required":["targetType","target","platform","locationCode","languageCode","limit"],"additionalProperties":false}}}},"responses":{"200":{"description":"Project-scoped indexed vendor research and provenance","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"preview":{"type":"object","properties":{"input":{"type":"object","properties":{"targetType":{"type":"string","enum":["keyword","domain"]},"target":{"type":"string","minLength":1,"maxLength":250},"platform":{"type":"string","enum":["google","chat_gpt"]},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":50,"type":"integer","minimum":1,"maximum":50}},"required":["targetType","target","platform","locationCode","languageCode","limit"],"additionalProperties":false},"fingerprint":{"type":"string"},"quota":{"type":"object","properties":{"period":{"type":"string"},"tasks":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","tasks","rows"],"additionalProperties":false},"storage":{"type":"object","properties":{"orgUsedOrHeldBytes":{"type":"number"},"orgLimitBytes":{"type":"number"},"deploymentLimitBytes":{"type":"number"},"reservationBytes":{"type":"number"}},"required":["orgUsedOrHeldBytes","orgLimitBytes","deploymentLimitBytes","reservationBytes"],"additionalProperties":false},"allowed":{"type":"boolean"},"reason":{"anyOf":[{"type":"string","enum":["research_allowance","storage_limit"]},{"type":"null"}]},"plannedTasks":{"type":"number","const":1},"maximumRows":{"type":"number"},"remainingAfter":{"type":"object","properties":{"tasks":{"type":"number"},"rows":{"type":"number"}},"required":["tasks","rows"],"additionalProperties":false},"source":{"type":"object","properties":{"provider":{"type":"string","const":"dataforseo"},"collectionMethod":{"type":"string","const":"vendor_api"},"dataset":{"type":"string"},"coverage":{"type":"string"}},"required":["provider","collectionMethod","dataset","coverage"],"additionalProperties":false}},"required":["input","fingerprint","quota","storage","allowed","reason","plannedTasks","maximumRows","remainingAfter","source"],"additionalProperties":false}},"required":["preview"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/indexed-mentions/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read up to 50 indexed research snapshots","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Project-scoped indexed vendor research and provenance","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"type":"array","items":{"type":"object","properties":{"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"periodId":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"scope":{"type":"object","properties":{"targetType":{"type":"string","enum":["keyword","domain"]},"target":{"type":"string","minLength":1,"maxLength":250},"platform":{"type":"string","enum":["google","chat_gpt"]},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":50,"type":"integer","minimum":1,"maximum":50}},"required":["targetType","target","platform","locationCode","languageCode","limit"],"additionalProperties":false},"requestConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quoteFingerprint":{"type":"string"},"policyVersion":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"reservedRows":{"type":"number"},"consumedTasks":{"type":"number"},"consumedRows":{"type":"number"},"reservedBytes":{"type":"number"},"retainedBytes":{"type":"number"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"sentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"providerTaskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"records":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["google","chat_gpt"]},"model_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"location_code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"language_code":{"type":"string"},"question":{"type":"string","minLength":1},"answer":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_response_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_response_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_web_search_based":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"sources":{"anyOf":[{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},{"type":"null"}]},"search_results":{"anyOf":[{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},{"type":"null"}]},"ai_search_volume":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]}},"required":["platform","location_code","language_code","question"],"additionalProperties":false}},{"type":"null"}]},"totalAvailable":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","jobId","status","sentAt","receivedAt","providerTaskId","providerStatusCode","billing","failure","responseHash","records","totalAvailable","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["example","id","orgId","projectId","projectOrgId","periodId","createdBy","scope","requestConfig","quoteFingerprint","policyVersion","status","reservationStatus","reservedRows","consumedTasks","consumedRows","reservedBytes","retainedBytes","createdAt","updatedAt","attempt"],"additionalProperties":false}}},"required":["research"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/indexed-mentions/{researchId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"researchId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read an indexed research snapshot","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Project-scoped indexed vendor research and provenance","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"anyOf":[{"type":"object","properties":{"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"periodId":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"scope":{"type":"object","properties":{"targetType":{"type":"string","enum":["keyword","domain"]},"target":{"type":"string","minLength":1,"maxLength":250},"platform":{"type":"string","enum":["google","chat_gpt"]},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":50,"type":"integer","minimum":1,"maximum":50}},"required":["targetType","target","platform","locationCode","languageCode","limit"],"additionalProperties":false},"requestConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quoteFingerprint":{"type":"string"},"policyVersion":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"reservedRows":{"type":"number"},"consumedTasks":{"type":"number"},"consumedRows":{"type":"number"},"reservedBytes":{"type":"number"},"retainedBytes":{"type":"number"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"sentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"providerTaskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"records":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["google","chat_gpt"]},"model_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"location_code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"language_code":{"type":"string"},"question":{"type":"string","minLength":1},"answer":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_response_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_response_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_web_search_based":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"sources":{"anyOf":[{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},{"type":"null"}]},"search_results":{"anyOf":[{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},{"type":"null"}]},"ai_search_volume":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]}},"required":["platform","location_code","language_code","question"],"additionalProperties":false}},{"type":"null"}]},"totalAvailable":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","jobId","status","sentAt","receivedAt","providerTaskId","providerStatusCode","billing","failure","responseHash","records","totalAvailable","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["example","id","orgId","projectId","projectOrgId","periodId","createdBy","scope","requestConfig","quoteFingerprint","policyVersion","status","reservationStatus","reservedRows","consumedTasks","consumedRows","reservedBytes","retainedBytes","createdAt","updatedAt","attempt"],"additionalProperties":false},{"type":"null"}]},"quota":{"type":"object","properties":{"period":{"type":"string"},"tasks":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","tasks","rows"],"additionalProperties":false}},"required":["research"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/indexed-mentions/{researchId}/evidence":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"researchId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read archived vendor response and hash","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Project-scoped indexed vendor research and provenance","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"evidence":{"type":"object","properties":{"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"rawResponse":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["example","rawResponse","responseHash","receivedAt"],"additionalProperties":false}},"required":["evidence"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/indexed-mentions/{researchId}/reconcile":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"researchId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Reconcile without a new provider call","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Project-scoped indexed vendor research and provenance","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"research":{"anyOf":[{"type":"object","properties":{"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectOrgId":{"anyOf":[{"type":"string"},{"type":"null"}]},"periodId":{"type":"string"},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"scope":{"type":"object","properties":{"targetType":{"type":"string","enum":["keyword","domain"]},"target":{"type":"string","minLength":1,"maxLength":250},"platform":{"type":"string","enum":["google","chat_gpt"]},"locationCode":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"languageCode":{"type":"string","pattern":"^[a-z]{2}(?:-[A-Z]{2})?$"},"limit":{"default":50,"type":"integer","minimum":1,"maximum":50}},"required":["targetType","target","platform","locationCode","languageCode","limit"],"additionalProperties":false},"requestConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"quoteFingerprint":{"type":"string"},"policyVersion":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"reservationStatus":{"type":"string","enum":["held","consumed","released"]},"reservedRows":{"type":"number"},"consumedTasks":{"type":"number"},"consumedRows":{"type":"number"},"reservedBytes":{"type":"number"},"retainedBytes":{"type":"number"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"attempt":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string","enum":["prepared","sent","completed","failed","unknown"]},"sentAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"providerTaskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"billing":{"type":"string","enum":["not_billed","reported","unknown"]},"failure":{"anyOf":[{"type":"string"},{"type":"null"}]},"responseHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"records":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["google","chat_gpt"]},"model_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"location_code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"language_code":{"type":"string"},"question":{"type":"string","minLength":1},"answer":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_response_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_response_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_web_search_based":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"sources":{"anyOf":[{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},{"type":"null"}]},"search_results":{"anyOf":[{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},{"type":"null"}]},"ai_search_volume":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]}},"required":["platform","location_code","language_code","question"],"additionalProperties":false}},{"type":"null"}]},"totalAvailable":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","jobId","status","sentAt","receivedAt","providerTaskId","providerStatusCode","billing","failure","responseHash","records","totalAvailable","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["example","id","orgId","projectId","projectOrgId","periodId","createdBy","scope","requestConfig","quoteFingerprint","policyVersion","status","reservationStatus","reservedRows","consumedTasks","consumedRows","reservedBytes","retainedBytes","createdAt","updatedAt","attempt"],"additionalProperties":false},{"type":"null"}]},"quota":{"type":"object","properties":{"period":{"type":"string"},"tasks":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false},"rows":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"held":{"type":"number"},"remaining":{"type":"number"}},"required":["limit","used","held","remaining"],"additionalProperties":false}},"required":["period","tasks","rows"],"additionalProperties":false}},"required":["research"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/indexed-mentions/questions":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List selected indexed questions","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Project-scoped indexed vendor research and provenance","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"questions":{"type":"array","items":{"type":"object","properties":{"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"sourceJobId":{"type":"string"},"sourceRecordIndex":{"type":"number"},"originalQuestion":{"type":"string"},"editedQuestion":{"type":"string"},"promptId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["example","id","orgId","projectId","sourceJobId","sourceRecordIndex","originalQuestion","editedQuestion","promptId","createdBy","createdAt","updatedAt"],"additionalProperties":false}}},"required":["questions"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Save an indexed question and edits","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"researchId":{"type":"string","minLength":1},"recordIndex":{"type":"integer","minimum":0,"maximum":49},"editedQuestion":{"type":"string","minLength":1,"maxLength":1000}},"required":["researchId","recordIndex","editedQuestion"],"additionalProperties":false}}}},"responses":{"201":{"description":"Project-scoped indexed vendor research and provenance","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"question":{"type":"object","properties":{"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"sourceJobId":{"type":"string"},"sourceRecordIndex":{"type":"number"},"originalQuestion":{"type":"string"},"editedQuestion":{"type":"string"},"promptId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["example","id","orgId","projectId","sourceJobId","sourceRecordIndex","originalQuestion","editedQuestion","promptId","createdBy","createdAt","updatedAt"],"additionalProperties":false}},"required":["question"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/indexed-mentions/questions/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read selected questions in one batch","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ids":{"maxItems":50,"type":"array","items":{"type":"string","minLength":1}}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Project-scoped indexed vendor research and provenance","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"questions":{"type":"array","items":{"type":"object","properties":{"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"sourceJobId":{"type":"string"},"sourceRecordIndex":{"type":"number"},"originalQuestion":{"type":"string"},"editedQuestion":{"type":"string"},"promptId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["example","id","orgId","projectId","sourceJobId","sourceRecordIndex","originalQuestion","editedQuestion","promptId","createdBy","createdAt","updatedAt"],"additionalProperties":false}}},"required":["questions"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/indexed-mentions/questions/{questionId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"questionId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Edit an unadopted question using its current revision","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"editedQuestion":{"type":"string","minLength":1,"maxLength":1000},"expectedUpdatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["editedQuestion","expectedUpdatedAt"],"additionalProperties":false}}}},"responses":{"200":{"description":"Project-scoped indexed vendor research and provenance","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"question":{"type":"object","properties":{"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"sourceJobId":{"type":"string"},"sourceRecordIndex":{"type":"number"},"originalQuestion":{"type":"string"},"editedQuestion":{"type":"string"},"promptId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["example","id","orgId","projectId","sourceJobId","sourceRecordIndex","originalQuestion","editedQuestion","promptId","createdBy","createdAt","updatedAt"],"additionalProperties":false}},"required":["question"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/indexed-mentions/questions/{questionId}/adopt":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"questionId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Explicitly create a tracked prompt without scanning","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"Project-scoped indexed vendor research and provenance","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"ok":{"type":"boolean"},"data":{"anyOf":[{"type":"object","properties":{"question":{"type":"object","properties":{"example":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"id":{"type":"string"},"orgId":{"type":"string"},"projectId":{"type":"string"},"sourceJobId":{"type":"string"},"sourceRecordIndex":{"type":"number"},"originalQuestion":{"type":"string"},"editedQuestion":{"type":"string"},"promptId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["example","id","orgId","projectId","sourceJobId","sourceRecordIndex","originalQuestion","editedQuestion","promptId","createdBy","createdAt","updatedAt"],"additionalProperties":false}},"required":["question"],"additionalProperties":false},{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false}]},"agent_guidance":{"type":"string"},"_meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"_human":{"type":"string"}},"required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/sentiment/{runId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"runId","in":"path","required":true,"schema":{"type":"string"}},{"name":"targetId","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":256}}],"get":{"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read saved sentiment evidence","responses":{"200":{"description":"Unevaluated saved evidence; no provider call or numeric score","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"405":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Unavailable until sentiment evaluation and activation approval","responses":{"200":{"description":"Unevaluated saved evidence; no provider call or numeric score","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"405":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"sentiment_evaluation_required; no effect or dispatch"},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/sentiment/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read up to twenty saved sentiment targets","responses":{"200":{"description":"Unevaluated saved evidence; no provider call or numeric score","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"405":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"targets":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"runId":{"type":"string","minLength":1,"maxLength":256},"targetId":{"type":"string","minLength":1,"maxLength":256}},"required":["runId","targetId"],"additionalProperties":false}}},"required":["targets"],"additionalProperties":false}}}}}},"/api/v1/projects/{projectId}/competitors":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"List bounded as-of identity and history pages with live competitor configuration","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompetitorListData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096}},{"name":"aliasCursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096}},{"name":"recordedCursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096}}],"description":"Identity membership, aliases, and recorded names use immutable cursor keys and one exact microsecond as-of boundary. Names, domains, retirement state, and active/retired counts are live on each page. Child cursors must be used with the identity page that returned them."},"post":{"summary":"Add one competitor for future matching without starting a scan","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"domain":{"type":"string","maxLength":253},"type":{"$ref":"#/components/schemas/CompetitorType"}}}}}}}},"/api/v1/projects/{projectId}/competitors/{competitorId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"competitorId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"patch":{"summary":"Edit, retire, or reactivate one retained competitor identity","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompetitorUpdateData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["expected","name","domain","retired"],"properties":{"expected":{"type":"object","additionalProperties":false,"required":["name","domain","retired"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"domain":{"type":["string","null"],"maxLength":253},"retired":{"type":"boolean"}}},"name":{"type":"string","minLength":1,"maxLength":120},"domain":{"type":["string","null"],"maxLength":253},"retired":{"type":"boolean"}}}}}}}},"/api/v1/projects/{projectId}/competitors/{competitorId}/type":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"competitorId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"patch":{"summary":"Label one competitor Direct or Search","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompetitorTypeData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"description":"A label only. It does not change what future answers match and starts no scan.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"$ref":"#/components/schemas/CompetitorType"}}}}}}}},"/api/v1/projects/{projectId}/competitors/types":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"patch":{"summary":"Label up to 50 competitors Direct or Search in one call","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompetitorTypesData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"description":"All items apply or none do. A label only: it does not change what future answers match and starts no scan.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["competitorId","type"],"properties":{"competitorId":{"type":"string","minLength":1,"maxLength":200},"type":{"$ref":"#/components/schemas/CompetitorType"}}}}}}}}}}},"/api/v1/projects/competitors/batch":{"post":{"summary":"List bounded competitor identity pages for up to 20 projects","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompetitorBatchData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["projectIds"],"properties":{"projectIds":{"type":"array","minItems":1,"maxItems":20,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":200}},"cursors":{"type":"object","additionalProperties":{"type":"string","minLength":1,"maxLength":4096}},"aliasCursors":{"type":"object","additionalProperties":{"type":"string","minLength":1,"maxLength":4096}},"recordedCursors":{"type":"object","additionalProperties":{"type":"string","minLength":1,"maxLength":4096}}}}}}}}},"/api/v1/projects/{projectId}/prompts/{promptId}/engines":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"promptId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update one question's engine choices without starting a scan","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["expectedEngines","engines","removeLegacyEngines"],"properties":{"expectedEngines":{"anyOf":[{"type":"array","maxItems":64,"items":{"type":"string","enum":["chatgpt","perplexity","gemini","claude","copilot","google_aio","grok","deepseek"]}},{"type":"null"}]},"engines":{"type":"array","minItems":1,"maxItems":8,"uniqueItems":true,"items":{"type":"string","enum":["perplexity","chatgpt","google_aio","deepseek"]}},"removeLegacyEngines":{"type":"array","maxItems":8,"uniqueItems":true,"items":{"type":"string","enum":["gemini","claude","copilot","grok"]}}}}}}}}},"/api/v1/projects/{projectId}/sources":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"engine","in":"query","required":false,"schema":{"type":"string","enum":["chatgpt","perplexity","gemini","claude","copilot","google_aio","grok","deepseek"]}},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["all","today","7d","14d","28d","30d","90d","custom"],"description":"Date range of the recorded answers, by when they were recorded. Nd is the N×24 hours before the request's instant (asOf when given); today is since 00:00 UTC; custom is whole UTC days from through to inclusive and needs both. Defaults to all. An unknown value, an inverted custom range or from/to without range=custom answers 422."}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date","description":"First UTC day of a custom range (YYYY-MM-DD). Only with range=custom."}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Last UTC day of a custom range (YYYY-MM-DD), inclusive; not before from. Only with range=custom."}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["all","cited","retrieved"]}},{"name":"domain","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":253}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":2048}}],"get":{"summary":"Read exact source totals and a bounded domain page","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectSourcesData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"description":"Source totals reflect the filtered history. URL examples are bounded and pagination is over live history."}},"/api/v1/projects/sources/batch":{"post":{"summary":"Read source totals for up to 20 projects","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectSourcesBatchData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectIds"],"properties":{"projectIds":{"type":"array","minItems":1,"maxItems":20,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":200}},"engine":{"type":"string","enum":["chatgpt","perplexity","gemini","claude","copilot","google_aio","grok","deepseek"]},"range":{"type":"string","enum":["all","today","7d","14d","28d","30d","90d","custom"],"description":"Date range of the recorded answers, by when they were recorded. Nd is the N×24 hours before the request's instant (asOf when given); today is since 00:00 UTC; custom is whole UTC days from through to inclusive and needs both. Defaults to all. An unknown value, an inverted custom range or from/to without range=custom answers 422."},"from":{"type":"string","format":"date","description":"First UTC day of a custom range (YYYY-MM-DD). Only with range=custom."},"to":{"type":"string","format":"date","description":"Last UTC day of a custom range (YYYY-MM-DD), inclusive; not before from. Only with range=custom."},"kind":{"type":"string","enum":["all","cited","retrieved"]},"domain":{"type":"string","maxLength":253}}}}}}}},"/api/v1/projects/{projectId}/responses/{runId}/export":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Export one saved response as a versioned JSON receipt","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ResponseExportData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"description":"Returns format, fixed filename and UTF-8 JSON text for one recorded answer. Null fields were not recorded; source kinds distinguish cited and retrieved. Each mention carries spans, every place the brand is named in rawAnswer as start and end character offsets; each source carries markerIds, the reference markers in the answer that point at it as the engine numbered them. Both are null for answers recorded before they were stored, and markerIds is null where an engine gives no markers. mentionCounting says how brand mentions were counted: by rules alone, or by rules plus the brand name disambiguation check with what it set aside."}},"/api/v1/health":{"get":{"summary":"Service health","security":[],"responses":{"200":{"description":"Healthy"}}}},"/api/v1/openapi":{"get":{"summary":"OpenAPI document","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document"}}}},"/api/v1/quota/usage":{"get":{"summary":"Get organization usage by meter","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UsageOverviewData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/billing":{"get":{"summary":"Read the workspace plan, status, period, allowances, plan prices and whether a new plan starts with the free trial, when a past-due plan stops, and any plan change scheduled for the period end (any member; status none when no subscription)","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/billing/checkout":{"post":{"summary":"Create a checkout link for a plan and interval (owners and admins; others get 404; 409 when the workspace already has a plan or the caller's email pays for another workspace; 422 when the payment provider refuses; 503 while billing is not enforced)","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/billing/portal":{"post":{"summary":"Create a private customer-portal link (owners and admins; others get 404; 409 until the workspace has a billing customer)","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quota/answers":{"get":{"summary":"Get the organization's answer allowance","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnswerQuotaData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/whoami":{"get":{"summary":"Current authenticated user","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Authenticated session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhoamiResponse"}}}},"401":{"description":"No authenticated session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhoamiResponse"}}}}}}},"/api/v1/projects":{"get":{"summary":"List projects","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"description":"With plan enforcement on, each project carries planPaused: true when it is above the plan's website limit and is not scanned. The newest websites are paused first unless the customer chose otherwise (POST /api/v1/workspace/plan-keep)."},"post":{"summary":"Create a manual project or confirm a saved enrichment; does not start scans","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"description":"Send manual project fields or enrichmentId and expectedRevision. Omitted manual question labels remain unknown.","content":{"application/json":{"schema":{"anyOf":[{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"enrichmentId":{"type":"string","minLength":1},"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["enrichmentId","expectedRevision"],"additionalProperties":false},{"type":"object","required":["name","aliases"],"properties":{"name":{"type":"string","minLength":1},"domain":{"type":"string"},"aliases":{"type":"array","minItems":1,"items":{"type":"string"}},"competitors":{"type":"array","maxItems":5,"items":{"type":"object"}},"prompts":{"type":"array","maxItems":20,"items":{"type":"object","properties":{"text":{"type":"string"},"engines":{"type":"array","items":{"type":"string"}},"topic":{"type":["string","null"],"maxLength":200},"branded":{"type":["boolean","null"]}}}}}}]}}}}}},"/api/v1/projects/batch":{"post":{"summary":"Read project summaries in a batch","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectSummaryBatchData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectIds"],"properties":{"projectIds":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","minLength":1}},"compare":{"type":"string","enum":["previous"],"description":"Opt in to exact adjacent recorded-window analytics: for range=7d, 14d, 28d, 30d or 90d the N×24 hours before asOf against the N×24 hours before that; for a finished custom range (its last day before today UTC) the range against the same number of whole days before it. all answers unavailable with reason unbounded_range, today unsupported_range, and a custom range that has not finished range_in_progress. periodDays on the result is the length of each period. Existing recent detail fields remain unchanged."},"asOf":{"type":"string","format":"date-time","description":"ISO instant with explicit Z/offset; must not be future. One captured instant across a batch."},"engine":{"type":"string","enum":["chatgpt","perplexity","gemini","claude","copilot","google_aio","grok","deepseek"]},"range":{"type":"string","enum":["all","today","7d","14d","28d","30d","90d","custom"],"description":"Date range of the recorded answers, by when they were recorded. Nd is the N×24 hours before the request's instant (asOf when given); today is since 00:00 UTC; custom is whole UTC days from through to inclusive and needs both. Defaults to all. An unknown value, an inverted custom range or from/to without range=custom answers 422."},"from":{"type":"string","format":"date","description":"First UTC day of a custom range (YYYY-MM-DD). Only with range=custom."},"to":{"type":"string","format":"date","description":"Last UTC day of a custom range (YYYY-MM-DD), inclusive; not before from. Only with range=custom."},"topic":{"type":"string","description":"Current topic: all, unknown, none (explicit no-topic), or value: followed by the exact literal topic. Applied within the latest 100 project runs.","anyOf":[{"enum":["all","unknown","none"]},{"pattern":"^value:[\\s\\S]+$","maxLength":206}]},"branded":{"type":"string","enum":["all","unknown","branded","unbranded"],"description":"Current user classification, including when selecting earlier answers."}}}}}}}},"/api/v1/projects/scans/batch":{"post":{"summary":"List scans for projects in a batch","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectIds"],"properties":{"projectIds":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","minLength":1}}}}}}}}},"/api/v1/prompts/runs/batch":{"post":{"summary":"List prompt runs in a batch","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["promptIds"],"properties":{"promptIds":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","minLength":1}}}}}}}}},"/api/v1/projects/{projectId}":{"patch":{"summary":"Update brand, site, confirmed aliases, exact match and the brand name disambiguation note (disambiguation, up to 1,000 characters, empty clears it; when set, an AI check sets aside answer matches the note says are not your brand, for scans queued afterwards); an unchanged request writes nothing, a stale expectedUpdatedAt returns 409 revision_conflict, and a real change invalidates recurring scan consent","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"brandName":{"type":"string","minLength":1,"maxLength":120},"domain":{"type":"string","minLength":1,"maxLength":253},"aliases":{"minItems":1,"maxItems":30,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"exactMatch":{"type":"boolean"},"disambiguation":{"type":"string","maxLength":1000},"expectedUpdatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["name","brandName","domain","aliases"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"summary":"Owner/admin only: permanently delete an idle project archive, preserving organization quota","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"confirmProjectId":{"type":"string","minLength":1},"confirmName":{"type":"string","minLength":1,"maxLength":120}},"required":["confirmProjectId","confirmName"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get project visibility","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectSummaryData"}}}]}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"compare","in":"query","schema":{"type":"string","enum":["previous"],"description":"Opt in to exact adjacent recorded-window analytics: for range=7d, 14d, 28d, 30d or 90d the N×24 hours before asOf against the N×24 hours before that; for a finished custom range (its last day before today UTC) the range against the same number of whole days before it. all answers unavailable with reason unbounded_range, today unsupported_range, and a custom range that has not finished range_in_progress. periodDays on the result is the length of each period. Existing recent detail fields remain unchanged."}},{"name":"asOf","in":"query","schema":{"type":"string","format":"date-time","description":"ISO instant with explicit Z/offset; must not be future. One captured instant across a batch."}},{"name":"engine","in":"query","schema":{"type":"string","enum":["chatgpt","perplexity","gemini","claude","copilot","google_aio","grok","deepseek"]}},{"name":"range","in":"query","schema":{"type":"string","enum":["all","today","7d","14d","28d","30d","90d","custom"],"description":"Date range of the recorded answers, by when they were recorded. Nd is the N×24 hours before the request's instant (asOf when given); today is since 00:00 UTC; custom is whole UTC days from through to inclusive and needs both. Defaults to all. An unknown value, an inverted custom range or from/to without range=custom answers 422."}},{"name":"from","in":"query","schema":{"type":"string","format":"date","description":"First UTC day of a custom range (YYYY-MM-DD). Only with range=custom."}},{"name":"to","in":"query","schema":{"type":"string","format":"date","description":"Last UTC day of a custom range (YYYY-MM-DD), inclusive; not before from. Only with range=custom."}},{"name":"topic","in":"query","schema":{"type":"string","description":"Current topic: all, unknown, none (explicit no-topic), or value: followed by the exact literal topic. Applied within the latest 100 project runs.","anyOf":[{"enum":["all","unknown","none"]},{"pattern":"^value:[\\s\\S]+$","maxLength":206}]}},{"name":"branded","in":"query","schema":{"type":"string","enum":["all","unknown","branded","unbranded"],"description":"Current user classification, including when selecting earlier answers."}}],"description":"Filters intersect the latest 100 non-example project runs, including unknown origins, before derived counts and returned 20 runs; a range narrower than those 100 runs is complete, while one that reaches past the oldest of them shows only the newest 100 and says so (sampleLimitReached); current labels are not historical answer metadata. Filtered sources cover selected recent runs; without filters, source counts cover all history. Configuration and next-scan counts always describe the whole project, not the filtered evidence."}},"/api/v1/projects/{projectId}/prompts":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create prompt","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/scans":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List project scans","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ScanListData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Start project scan","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["acceptedQuoteFingerprint"],"properties":{"acceptedQuoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}}}}}}}},"/api/v1/projects/{projectId}/scans/{scanId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"scanId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get scan progress","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ScanDetailData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/scans/{scanId}/details":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"scanId","in":"path","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":25}}],"get":{"summary":"Read a bounded page of scan job and answer receipts","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ScanReceiptPageData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"description":"Durable job status remains separate from saved-answer analysis. Each answer discloses collection method and provider, fixture or unknown origin. nextCursor continues both bounded receipt streams; legacyMissingJobRecords is missing archive evidence, not pagination."}},"/api/v1/projects/{projectId}/scans/details/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Read bounded receipt pages for up to 20 scans","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ScanReceiptBatchData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["scans"],"properties":{"scans":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["scanId"],"properties":{"scanId":{"type":"string","minLength":1},"cursor":{"type":"string","minLength":1,"maxLength":4096},"limit":{"type":"integer","minimum":1,"maximum":50,"default":25}}}}}}}}}}},"/api/v1/projects/{projectId}/scans/preview":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Preview current scan answer units","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"description":"skipped lists prompt and engine pairs left out: no reason when collection is unavailable, reason plan for an engine the plan does not run, reason over_plan for a question paused above the plan's question limit. A website paused above the plan's limit, or a paused question previewed alone, answers 422 plan_limit.","parameters":[{"name":"promptId","in":"query","required":false,"description":"Supply with engine to preview one prompt.","schema":{"type":"string","minLength":1}},{"name":"engine","in":"query","required":false,"description":"Supply with promptId; must be implemented.","schema":{"type":"string","enum":["perplexity","chatgpt","google_aio","deepseek"]}}]}},"/api/v1/projects/{projectId}/proofs":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"List proofs","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProofListData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Record a change and consent to proof checkpoints","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProofCreateData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["promptId","baselineRunIds","changedAt","whatChanged","url","changeKind","acceptedAnswerCount","acceptedImmediateAnswerCount","acceptedQuoteFingerprint"],"properties":{"promptId":{"type":"string","minLength":1},"baselineRunIds":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"string","minLength":1}},"changedAt":{"type":"string","format":"date-time"},"whatChanged":{"type":"string","minLength":1,"maxLength":1000},"url":{"type":"string","format":"uri","pattern":"^https?://"},"changeKind":{"type":"string","enum":["content","schema","backlink","distribution"]},"acceptedAnswerCount":{"type":"integer","minimum":0},"acceptedImmediateAnswerCount":{"type":"integer","minimum":0},"acceptedQuoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}}}}}}}},"/api/v1/projects/{projectId}/proofs/preview":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Preview proof checkpoint answer units","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProofPreviewData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"promptId","in":"query","required":true,"schema":{"type":"string","minLength":1}},{"name":"baselineRunId","in":"query","required":true,"style":"form","explode":true,"schema":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"string","minLength":1}}},{"name":"changedAt","in":"query","required":true,"schema":{"type":"string","format":"date-time"}}]}},"/api/v1/projects/{projectId}/proofs/batch":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Read proofs in a batch","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProofBatchData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["proofIds"],"properties":{"proofIds":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1}}}}}}}}},"/api/v1/projects/{projectId}/proofs/{proofId}":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"proofId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Get a proof and its receipts","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProofDetailData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/proofs/{proofId}/measure":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"proofId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"post":{"summary":"Schedule due consented proof checkpoints","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProofMeasureData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/projects/{projectId}/proofs/{proofId}/consent":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"proofId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Preview remaining proof consent","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProofConsentData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"put":{"summary":"Renew proof consent","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProofConsentData"}}}]}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fingerprint","acceptedAnswerCount","acceptedImmediateAnswerCount"],"properties":{"fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"acceptedAnswerCount":{"type":"integer","minimum":0},"acceptedImmediateAnswerCount":{"type":"integer","minimum":0}}}}}}}},"/api/v1/projects/{projectId}/cadence/preview":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Preview recurring scan consent","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CadencePreviewData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"name":"frequency","in":"query","required":true,"schema":{"type":"string","enum":["daily","weekly","monthly"]}}]}},"/api/v1/projects/{projectId}/cadence":{"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"get":{"summary":"Get recurring scan status","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CadenceStatusData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"put":{"summary":"Enable or disable recurring scans","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CadenceUpdateData"}}}]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["enabled"],"properties":{"enabled":{"const":false}}},{"type":"object","required":["enabled","frequency","fingerprint","acceptedAnswerCount"],"properties":{"enabled":{"const":true},"frequency":{"type":"string","enum":["daily","weekly","monthly"]},"fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"acceptedAnswerCount":{"type":"integer","minimum":1}}}]}}}}}},"/api/v1/prompts/{promptId}/runs":{"parameters":[{"name":"promptId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List prompt runs","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"description":"Lists non-example runs, including unknown origins. Known examples remain accessible as direct receipts."},"post":{"summary":"Start prompt run","security":[{"bearerAuth":[]},{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["acceptedQuoteFingerprint"],"properties":{"engine":{"$ref":"#/components/schemas/Engine"},"acceptedQuoteFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}}}}}}}},"/api/v1/api-keys":{"get":{"summary":"List API keys","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"summary":"Create scoped API key","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Project grants are read-only unless canWrite is enabled. Organization permissions default to false. Write access to created projects requires project creation permission.","properties":{"label":{"type":"string","minLength":1,"maxLength":120},"projects":{"type":"array","maxItems":100,"default":[],"items":{"type":"object","required":["projectId"],"properties":{"projectId":{"type":"string","minLength":1},"canWrite":{"type":"boolean","default":false}}}},"canReadQuota":{"type":"boolean","default":false},"canCreateProject":{"type":"boolean","default":false},"canWriteCreatedProject":{"type":"boolean","default":false},"canEnrichSite":{"type":"boolean","default":false}}}}}}}},"/api/v1/api-keys/{keyId}":{"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Revoke API key","security":[{"sessionAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiEnvelope"}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/jobs/run-prompt":{"post":{"summary":"Process durable scan job","responses":{"200":{"description":"Processed"},"401":{"description":"Invalid signature"},"489":{"description":"Non-retryable job error"}}}},"/api/v1/cron/scans":{"post":{"summary":"Run scheduled scans","responses":{"200":{"description":"Scheduled scans started"},"401":{"description":"Invalid signature"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"rcl_ API key"},"sessionAuth":{"type":"apiKey","in":"cookie","name":"sb-<project-ref>-auth-token","description":"Supabase SSR browser session. The default cookie name is sb-<project-ref>-auth-token and may be chunked; this app forwards the complete Supabase cookie set. API keys cannot call session-only endpoints."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1},"description":"Replaying a completed write returns its stored response without a second effect."}},"schemas":{"ProjectResponsesData":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"responses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"promptId":{"type":"string"},"promptText":{"type":"string"},"promptTextRecorded":{"type":"boolean"},"topic":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"branded":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"promptActive":{"type":"boolean"},"engine":{"type":"string","enum":["chatgpt","perplexity","gemini","claude","copilot","google_aio","grok","deepseek"]},"collectionMethod":{"type":"string","enum":["api","scrape","vendor_api"]},"answerOrigin":{"anyOf":[{"type":"string","enum":["provider","fixture"]},{"type":"null"}]},"verdict":{"anyOf":[{"type":"string","enum":["strong","cited","retrieved","mentioned_only","invisible"]},{"type":"null"}]},"yourPosition":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"mentionedYou":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"excerpt":{"type":"string"},"brands":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string"},"brandKind":{"anyOf":[{"type":"string","enum":["you","competitor","other"]},{"type":"null"}]},"position":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["brand","brandKind","position"],"additionalProperties":false}},"domains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"kind":{"type":"string","enum":["cited","retrieved"]},"isYours":{"type":"boolean"}},"required":["domain","kind","isYours"],"additionalProperties":false}},"citationCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"success":{"type":"boolean"},"analysisError":{"anyOf":[{"type":"string"},{"type":"null"}]},"runAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","promptId","promptText","promptTextRecorded","topic","branded","promptActive","engine","collectionMethod","answerOrigin","verdict","yourPosition","mentionedYou","excerpt","brands","domains","citationCount","success","analysisError","runAt"],"additionalProperties":false}},"totals":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"named":{"type":"integer","minimum":0,"maximum":9007199254740991},"cited":{"type":"integer","minimum":0,"maximum":9007199254740991},"retrieved":{"type":"integer","minimum":0,"maximum":9007199254740991},"namingUnmeasured":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["total","named","cited","retrieved","namingUnmeasured"],"additionalProperties":false},"page":{"type":"object","properties":{"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"nextOffset":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["offset","limit","total","nextOffset"],"additionalProperties":false},"facets":{"type":"object","properties":{"engines":{"type":"array","items":{"type":"string"}},"topics":{"type":"array","items":{"type":"string"}}},"required":["engines","topics"],"additionalProperties":false},"coverage":{"type":"object","properties":{"liveHistory":{"type":"boolean","const":true},"labels":{"type":"string","const":"current"},"archivedQuestionText":{"type":"string","enum":["complete","partial"]}},"required":["liveHistory","labels","archivedQuestionText"],"additionalProperties":false}},"required":["responses","totals","page","facets","coverage"],"additionalProperties":false},"ProjectResponsesBatchData":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"projects":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"responses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"promptId":{"type":"string"},"promptText":{"type":"string"},"promptTextRecorded":{"type":"boolean"},"topic":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"branded":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"promptActive":{"type":"boolean"},"engine":{"type":"string","enum":["chatgpt","perplexity","gemini","claude","copilot","google_aio","grok","deepseek"]},"collectionMethod":{"type":"string","enum":["api","scrape","vendor_api"]},"answerOrigin":{"anyOf":[{"type":"string","enum":["provider","fixture"]},{"type":"null"}]},"verdict":{"anyOf":[{"type":"string","enum":["strong","cited","retrieved","mentioned_only","invisible"]},{"type":"null"}]},"yourPosition":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"mentionedYou":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"excerpt":{"type":"string"},"brands":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string"},"brandKind":{"anyOf":[{"type":"string","enum":["you","competitor","other"]},{"type":"null"}]},"position":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["brand","brandKind","position"],"additionalProperties":false}},"domains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"kind":{"type":"string","enum":["cited","retrieved"]},"isYours":{"type":"boolean"}},"required":["domain","kind","isYours"],"additionalProperties":false}},"citationCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"success":{"type":"boolean"},"analysisError":{"anyOf":[{"type":"string"},{"type":"null"}]},"runAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","promptId","promptText","promptTextRecorded","topic","branded","promptActive","engine","collectionMethod","answerOrigin","verdict","yourPosition","mentionedYou","excerpt","brands","domains","citationCount","success","analysisError","runAt"],"additionalProperties":false}},"totals":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"named":{"type":"integer","minimum":0,"maximum":9007199254740991},"cited":{"type":"integer","minimum":0,"maximum":9007199254740991},"retrieved":{"type":"integer","minimum":0,"maximum":9007199254740991},"namingUnmeasured":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["total","named","cited","retrieved","namingUnmeasured"],"additionalProperties":false},"page":{"type":"object","properties":{"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"nextOffset":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["offset","limit","total","nextOffset"],"additionalProperties":false},"facets":{"type":"object","properties":{"engines":{"type":"array","items":{"type":"string"}},"topics":{"type":"array","items":{"type":"string"}}},"required":["engines","topics"],"additionalProperties":false},"coverage":{"type":"object","properties":{"liveHistory":{"type":"boolean","const":true},"labels":{"type":"string","const":"current"},"archivedQuestionText":{"type":"string","enum":["complete","partial"]}},"required":["liveHistory","labels","archivedQuestionText"],"additionalProperties":false},"projectId":{"type":"string"}},"required":["responses","totals","page","facets","coverage","projectId"],"additionalProperties":false}}},"required":["projects"],"additionalProperties":false},"PromptLifecycleData":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"prompt":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"text":{"type":"string"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}]},"branded":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"intent":{"anyOf":[{"type":"string","enum":["informational","commercial","transactional","navigational"]},{"type":"null"}]},"engines":{"anyOf":[{"type":"array","items":{"type":"string","enum":["chatgpt","perplexity","gemini","claude","copilot","google_aio","grok","deepseek"]}},{"type":"null"}]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["id","projectId","text","topic","branded","intent","engines","isActive","createdAt","updatedAt"],"additionalProperties":false},"changed":{"type":"boolean"},"cadenceConsentInvalidated":{"type":"boolean"}},"required":["prompt","changed","cadenceConsentInvalidated"],"additionalProperties":false},"PromptStatusBatchData":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"promptId":{"type":"string"},"outcome":{"type":"string","enum":["updated","unchanged","conflict","not_found"]},"isActive":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["promptId","outcome","isActive"],"additionalProperties":false}},"updatedCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"cadenceConsentInvalidated":{"type":"boolean"}},"required":["results","updatedCount","cadenceConsentInvalidated"],"additionalProperties":false},"PromptDeleteData":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"promptId":{"type":"string"},"outcome":{"type":"string","enum":["deleted","already_deleted"]},"cadenceConsentInvalidated":{"type":"boolean"}},"required":["promptId","outcome","cadenceConsentInvalidated"],"additionalProperties":false},"PromptDeleteBatchData":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"promptId":{"type":"string"},"outcome":{"type":"string","enum":["deleted","already_deleted","not_found"]}},"required":["promptId","outcome"],"additionalProperties":false}},"deletedCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"cadenceConsentInvalidated":{"type":"boolean"}},"required":["results","deletedCount","cadenceConsentInvalidated"],"additionalProperties":false},"PromptCreateBatchData":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"outcome":{"type":"string","enum":["created","duplicate"]},"promptId":{"type":"string"}},"required":["text","outcome","promptId"],"additionalProperties":false}},"createdCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"cadenceConsentInvalidated":{"type":"boolean"}},"required":["results","createdCount","cadenceConsentInvalidated"],"additionalProperties":false},"PromptExportData":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"format":{"type":"string","const":"csv"},"filename":{"type":"string"},"text":{"type":"string"},"rowCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"perspective":{"type":"string"}},"required":["format","filename","text","rowCount","perspective"],"additionalProperties":false},"CompetitorType":{"type":"string","enum":["direct","search"],"description":"direct sells what you sell; search shows up in the same searches and answers."},"CompetitorTypeData":{"type":"object","additionalProperties":false,"required":["competitor","changed"],"properties":{"competitor":{"$ref":"#/components/schemas/CompetitorConfiguration"},"changed":{"type":"boolean"}}},"CompetitorTypesData":{"type":"object","additionalProperties":false,"required":["competitors","changedCount"],"properties":{"competitors":{"type":"array","items":{"$ref":"#/components/schemas/CompetitorConfiguration"}},"changedCount":{"type":"integer","minimum":0}}},"CompetitorConfiguration":{"type":"object","additionalProperties":false,"required":["id","projectId","name","domain","type","retiredAt","createdAt"],"properties":{"id":{"type":"string"},"projectId":{"type":"string"},"name":{"type":"string"},"domain":{"type":["string","null"]},"type":{"$ref":"#/components/schemas/CompetitorType"},"retiredAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"CompetitorAliasCoverage":{"type":"object","additionalProperties":false,"required":["pageLimit","returnedAliases","omittedAliases","cursorApplied","history","asOf"],"properties":{"pageLimit":{"type":"integer","minimum":1},"returnedAliases":{"type":"integer","minimum":0},"omittedAliases":{"type":"integer","minimum":0},"cursorApplied":{"type":"boolean"},"history":{"type":"string","const":"as_of"},"asOf":{"type":"string","format":"date-time"}}},"CompetitorRecordedCoverage":{"type":"object","additionalProperties":false,"required":["pageLimit","returnedNames","omittedNames","cursorApplied","history","asOf"],"properties":{"pageLimit":{"type":"integer","minimum":1},"returnedNames":{"type":"integer","minimum":0},"omittedNames":{"type":"integer","minimum":0},"cursorApplied":{"type":"boolean"},"history":{"type":"string","const":"as_of"},"asOf":{"type":"string","format":"date-time"}}},"CompetitorIdentity":{"type":"object","additionalProperties":false,"required":["id","projectId","name","domain","type","retiredAt","createdAt","aliases","aliasCount","aliasNextCursor","aliasCoverage","recordedNames","recordedNameCount","recordedMentionCount","recordedNextCursor","recordedCoverage"],"properties":{"id":{"type":"string"},"projectId":{"type":"string"},"name":{"type":"string"},"domain":{"type":["string","null"]},"type":{"$ref":"#/components/schemas/CompetitorType"},"retiredAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"aliases":{"type":"array","items":{"type":"string"}},"aliasCount":{"type":"integer","minimum":0},"aliasNextCursor":{"type":["string","null"]},"aliasCoverage":{"$ref":"#/components/schemas/CompetitorAliasCoverage"},"recordedNames":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["name","mentions"],"properties":{"name":{"type":"string"},"mentions":{"type":"integer","minimum":1}}}},"recordedNameCount":{"type":"integer","minimum":0},"recordedMentionCount":{"type":"integer","minimum":0},"recordedNextCursor":{"type":["string","null"]},"recordedCoverage":{"$ref":"#/components/schemas/CompetitorRecordedCoverage"}}},"CompetitorListCoverage":{"type":"object","additionalProperties":false,"required":["identityPageLimit","identityCount","retiredIdentityCount","returnedIdentityCount","omittedIdentityCount","identityHistory","configuration","identityCountScope","activeRetiredCountScope","asOf"],"properties":{"identityPageLimit":{"type":"integer","minimum":1},"identityCount":{"type":"integer","minimum":0},"retiredIdentityCount":{"type":"integer","minimum":0},"returnedIdentityCount":{"type":"integer","minimum":0},"omittedIdentityCount":{"type":"integer","minimum":0},"identityHistory":{"type":"string","const":"as_of"},"configuration":{"type":"string","const":"live"},"identityCountScope":{"type":"string","const":"as_of"},"activeRetiredCountScope":{"type":"string","const":"as_of_identities_live_retirement"},"asOf":{"type":"string","format":"date-time"}}},"CompetitorListData":{"type":"object","additionalProperties":false,"required":["projectId","activeCount","identities","nextCursor","coverage"],"properties":{"projectId":{"type":"string"},"activeCount":{"type":"integer","minimum":0},"identities":{"type":"array","items":{"$ref":"#/components/schemas/CompetitorIdentity"}},"nextCursor":{"type":["string","null"]},"coverage":{"$ref":"#/components/schemas/CompetitorListCoverage"}}},"CompetitorBatchData":{"type":"object","additionalProperties":false,"required":["projects"],"properties":{"projects":{"type":"array","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/CompetitorListData"}}}},"CompetitorUpdateData":{"type":"object","additionalProperties":false,"required":["competitor","changed"],"properties":{"competitor":{"$ref":"#/components/schemas/CompetitorConfiguration"},"changed":{"type":"boolean"}}},"ProjectSourcesBatchData":{"type":"object","required":["projects"],"properties":{"projects":{"type":"array","maxItems":20,"items":{"allOf":[{"$ref":"#/components/schemas/ProjectSourcesData"},{"type":"object","required":["projectId"],"properties":{"projectId":{"type":"string"}}}]}}}},"ProjectSourcesData":{"type":"object","required":["totals","domains","nextCursor","coverage"],"properties":{"totals":{"type":"object","required":["cited","retrieved","domains"],"properties":{"cited":{"type":"integer"},"retrieved":{"type":"integer"},"domains":{"type":"integer"}}},"domains":{"type":"array","maxItems":50,"items":{"type":"object","required":["domain","cited","retrieved","isYours","distinctUrls","distinctUrlKinds","urls","hasMoreUrls"],"properties":{"domain":{"type":"string"},"cited":{"type":"integer"},"retrieved":{"type":"integer"},"isYours":{"type":"boolean"},"distinctUrls":{"type":"integer"},"distinctUrlKinds":{"type":"integer"},"urls":{"type":"array","maxItems":10,"items":{"type":"object","required":["url","kind","runId"],"properties":{"url":{"type":"string"},"title":{"type":["string","null"]},"kind":{"type":"string","enum":["cited","retrieved"]},"runId":{"type":"string"}}}},"hasMoreUrls":{"type":"boolean"}}}},"nextCursor":{"type":["string","null"]},"coverage":{"type":"object","required":["maxDomains","maxUrlExamplesPerDomain","omittedDomains","liveHistory","asOf"],"properties":{"maxDomains":{"type":"integer"},"maxUrlExamplesPerDomain":{"type":"integer"},"omittedDomains":{"type":"integer"},"liveHistory":{"type":"boolean"},"asOf":{"type":["string","null"],"format":"date-time"}}}}},"ResponseExportData":{"type":"object","required":["format","filename","text"],"properties":{"format":{"type":"string","const":"json"},"filename":{"type":"string","const":"response.json"},"text":{"type":"string","description":"Versioned JSON receipt serialized as UTF-8 text."}}},"UsageOverviewData":{"type":"object","required":["usage"],"properties":{"usage":{"type":"object","required":["period","answers","keywords","serp","indexedMentions","backlinks","generation","crawlUsage"],"properties":{"period":{"type":"string","format":"date"},"answers":{"anyOf":[{"$ref":"#/components/schemas/UsageMeter"},{"type":"null"}]},"keywords":{"anyOf":[{"$ref":"#/components/schemas/UsageRequestsRows"},{"type":"null"}]},"serp":{"anyOf":[{"$ref":"#/components/schemas/UsageMeter"},{"type":"null"}]},"indexedMentions":{"anyOf":[{"$ref":"#/components/schemas/UsageTasksRows"},{"type":"null"}]},"backlinks":{"anyOf":[{"$ref":"#/components/schemas/UsageTasksRows"},{"type":"null"}]},"generation":{"anyOf":[{"type":"object","required":["attempts"],"properties":{"attempts":{"$ref":"#/components/schemas/UsageMeter"}}},{"type":"null"}]},"crawlUsage":{"type":"null"}}}}},"UsageMeter":{"type":"object","required":["limit","used","held","remaining"],"properties":{"limit":{"type":"integer","minimum":0},"used":{"type":"integer","minimum":0},"held":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0}}},"UsageRequestsRows":{"type":"object","required":["requests","candidateRows"],"properties":{"requests":{"$ref":"#/components/schemas/UsageMeter"},"candidateRows":{"$ref":"#/components/schemas/UsageMeter"}}},"UsageTasksRows":{"type":"object","required":["tasks","requestedRows"],"properties":{"tasks":{"$ref":"#/components/schemas/UsageMeter"},"requestedRows":{"$ref":"#/components/schemas/UsageMeter"}}},"ScanDetailData":{"type":"object","required":["scan","jobCounts","engineOutcomes","dispatchReadiness","exampleAnswerCount","analysisErrorCount","attentionCheckCount","consentBlockedCount"],"properties":{"scan":{"type":"object","required":["id","projectId","status","totalJobs","completedJobs","failedJobs","durationMs","triggeredBy","startedAt","finishedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"projectId":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","partial","failed"]},"totalJobs":{"type":"integer"},"completedJobs":{"type":"integer"},"failedJobs":{"type":"integer"},"durationMs":{"type":["integer","null"]},"triggeredBy":{"type":"string","enum":["cron","user","agent","proof"]},"startedAt":{"type":["string","null"],"format":"date-time"},"finishedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"jobCounts":{"type":"object","required":["pending","queued","running","succeeded","failed","unknown"],"properties":{"pending":{"type":"integer"},"queued":{"type":"integer"},"running":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"unknown":{"type":"integer"}}},"engineOutcomes":{"anyOf":[{"type":"array","items":{"type":"object","required":["engine","status","count"],"properties":{"engine":{"$ref":"#/components/schemas/Engine"},"status":{"type":"string","enum":["pending","queued","running","succeeded","failed","unknown"]},"count":{"type":"integer"}}}},{"type":"null"}],"description":"Recorded per-engine job states when all scan jobs have engine details; null for incomplete legacy evidence. Succeeded means collected, not necessarily analyzed."},"dispatchReadiness":{"type":"object","required":["ready","reason"],"properties":{"ready":{"type":"boolean"},"reason":{"type":["string","null"]}}},"exampleAnswerCount":{"type":"integer"},"analysisErrorCount":{"type":"integer"},"attentionCheckCount":{"type":"integer"},"consentBlockedCount":{"type":"integer"}}},"ScanReceiptPageData":{"type":"object","required":["scan","jobCounts","engineOutcomes","dispatchReadiness","exampleAnswerCount","analysisErrorCount","attentionCheckCount","consentBlockedCount","jobDetails"],"properties":{"scan":{"type":"object","required":["id","projectId","status","totalJobs","completedJobs","failedJobs","durationMs","triggeredBy","startedAt","finishedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"projectId":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","partial","failed"]},"totalJobs":{"type":"integer"},"completedJobs":{"type":"integer"},"failedJobs":{"type":"integer"},"durationMs":{"type":["integer","null"]},"triggeredBy":{"type":"string","enum":["cron","user","agent","proof"]},"startedAt":{"type":["string","null"],"format":"date-time"},"finishedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"jobCounts":{"type":"object","required":["pending","queued","running","succeeded","failed","unknown"],"properties":{"pending":{"type":"integer"},"queued":{"type":"integer"},"running":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"unknown":{"type":"integer"}}},"engineOutcomes":{"anyOf":[{"type":"array","items":{"type":"object","required":["engine","status","count"],"properties":{"engine":{"$ref":"#/components/schemas/Engine"},"status":{"type":"string","enum":["pending","queued","running","succeeded","failed","unknown"]},"count":{"type":"integer"}}}},{"type":"null"}],"description":"Recorded per-engine job states when all scan jobs have engine details; null for incomplete legacy evidence. Succeeded means collected, not necessarily analyzed."},"dispatchReadiness":{"type":"object","required":["ready","reason"],"properties":{"ready":{"type":"boolean"},"reason":{"type":["string","null"]}}},"exampleAnswerCount":{"type":"integer"},"analysisErrorCount":{"type":"integer"},"attentionCheckCount":{"type":"integer"},"consentBlockedCount":{"type":"integer"},"jobDetails":{"type":"object","required":["jobs","unmatchedAnswers","limit","nextCursor","hasMore","totals","legacyMissingJobRecords"],"properties":{"jobs":{"type":"array","items":{"type":"object","required":["id","promptId","promptText","engine","status","createdAt","updatedAt","answer"],"properties":{"id":{"type":"string"},"promptId":{"type":"string"},"promptText":{"type":["string","null"]},"engine":{"$ref":"#/components/schemas/Engine"},"status":{"type":"string","enum":["pending","queued","running","succeeded","failed","unknown"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"answer":{"anyOf":[{"type":"object","required":["id","scanJobId","promptId","promptText","engine","collectionMethod","answerOrigin","verdict","success","analysisError","runAt"],"properties":{"id":{"type":"string"},"scanJobId":{"type":["string","null"]},"promptId":{"type":"string"},"promptText":{"type":["string","null"]},"engine":{"$ref":"#/components/schemas/Engine"},"collectionMethod":{"type":"string","enum":["api","scrape","vendor_api"]},"answerOrigin":{"type":["string","null"],"enum":["provider","fixture",null]},"verdict":{"type":["string","null"],"enum":["strong","cited","retrieved","mentioned_only","invisible",null]},"success":{"type":"boolean"},"analysisError":{"type":["string","null"]},"runAt":{"type":"string","format":"date-time"}}},{"type":"null"}]}}}},"unmatchedAnswers":{"type":"array","items":{"type":"object","required":["id","scanJobId","promptId","promptText","engine","collectionMethod","answerOrigin","verdict","success","analysisError","runAt"],"properties":{"id":{"type":"string"},"scanJobId":{"type":["string","null"]},"promptId":{"type":"string"},"promptText":{"type":["string","null"]},"engine":{"$ref":"#/components/schemas/Engine"},"collectionMethod":{"type":"string","enum":["api","scrape","vendor_api"]},"answerOrigin":{"type":["string","null"],"enum":["provider","fixture",null]},"verdict":{"type":["string","null"],"enum":["strong","cited","retrieved","mentioned_only","invisible",null]},"success":{"type":"boolean"},"analysisError":{"type":["string","null"]},"runAt":{"type":"string","format":"date-time"}}}},"limit":{"type":"integer"},"nextCursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"totals":{"type":"object","required":["jobRecords","answerRecords","unmatchedAnswerRecords"],"properties":{"jobRecords":{"type":"integer"},"answerRecords":{"type":"integer"},"unmatchedAnswerRecords":{"type":"integer"}}},"legacyMissingJobRecords":{"type":"integer"}}}}},"ScanReceiptBatchData":{"type":"object","required":["scans"],"properties":{"scans":{"type":"array","items":{"type":"object","required":["scanId","detail"],"properties":{"scanId":{"type":"string"},"detail":{"type":"object","required":["scan","jobCounts","engineOutcomes","dispatchReadiness","exampleAnswerCount","analysisErrorCount","attentionCheckCount","consentBlockedCount","jobDetails"],"properties":{"scan":{"type":"object","required":["id","projectId","status","totalJobs","completedJobs","failedJobs","durationMs","triggeredBy","startedAt","finishedAt","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"projectId":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","partial","failed"]},"totalJobs":{"type":"integer"},"completedJobs":{"type":"integer"},"failedJobs":{"type":"integer"},"durationMs":{"type":["integer","null"]},"triggeredBy":{"type":"string","enum":["cron","user","agent","proof"]},"startedAt":{"type":["string","null"],"format":"date-time"},"finishedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"jobCounts":{"type":"object","required":["pending","queued","running","succeeded","failed","unknown"],"properties":{"pending":{"type":"integer"},"queued":{"type":"integer"},"running":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"unknown":{"type":"integer"}}},"engineOutcomes":{"anyOf":[{"type":"array","items":{"type":"object","required":["engine","status","count"],"properties":{"engine":{"$ref":"#/components/schemas/Engine"},"status":{"type":"string","enum":["pending","queued","running","succeeded","failed","unknown"]},"count":{"type":"integer"}}}},{"type":"null"}],"description":"Recorded per-engine job states when all scan jobs have engine details; null for incomplete legacy evidence. Succeeded means collected, not necessarily analyzed."},"dispatchReadiness":{"type":"object","required":["ready","reason"],"properties":{"ready":{"type":"boolean"},"reason":{"type":["string","null"]}}},"exampleAnswerCount":{"type":"integer"},"analysisErrorCount":{"type":"integer"},"attentionCheckCount":{"type":"integer"},"consentBlockedCount":{"type":"integer"},"jobDetails":{"type":"object","required":["jobs","unmatchedAnswers","limit","nextCursor","hasMore","totals","legacyMissingJobRecords"],"properties":{"jobs":{"type":"array","items":{"type":"object","required":["id","promptId","promptText","engine","status","createdAt","updatedAt","answer"],"properties":{"id":{"type":"string"},"promptId":{"type":"string"},"promptText":{"type":["string","null"]},"engine":{"$ref":"#/components/schemas/Engine"},"status":{"type":"string","enum":["pending","queued","running","succeeded","failed","unknown"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"answer":{"anyOf":[{"type":"object","required":["id","scanJobId","promptId","promptText","engine","collectionMethod","answerOrigin","verdict","success","analysisError","runAt"],"properties":{"id":{"type":"string"},"scanJobId":{"type":["string","null"]},"promptId":{"type":"string"},"promptText":{"type":["string","null"]},"engine":{"$ref":"#/components/schemas/Engine"},"collectionMethod":{"type":"string","enum":["api","scrape","vendor_api"]},"answerOrigin":{"type":["string","null"],"enum":["provider","fixture",null]},"verdict":{"type":["string","null"],"enum":["strong","cited","retrieved","mentioned_only","invisible",null]},"success":{"type":"boolean"},"analysisError":{"type":["string","null"]},"runAt":{"type":"string","format":"date-time"}}},{"type":"null"}]}}}},"unmatchedAnswers":{"type":"array","items":{"type":"object","required":["id","scanJobId","promptId","promptText","engine","collectionMethod","answerOrigin","verdict","success","analysisError","runAt"],"properties":{"id":{"type":"string"},"scanJobId":{"type":["string","null"]},"promptId":{"type":"string"},"promptText":{"type":["string","null"]},"engine":{"$ref":"#/components/schemas/Engine"},"collectionMethod":{"type":"string","enum":["api","scrape","vendor_api"]},"answerOrigin":{"type":["string","null"],"enum":["provider","fixture",null]},"verdict":{"type":["string","null"],"enum":["strong","cited","retrieved","mentioned_only","invisible",null]},"success":{"type":"boolean"},"analysisError":{"type":["string","null"]},"runAt":{"type":"string","format":"date-time"}}}},"limit":{"type":"integer"},"nextCursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"totals":{"type":"object","required":["jobRecords","answerRecords","unmatchedAnswerRecords"],"properties":{"jobRecords":{"type":"integer"},"answerRecords":{"type":"integer"},"unmatchedAnswerRecords":{"type":"integer"}}},"legacyMissingJobRecords":{"type":"integer"}}}}}}}}}},"ScanListData":{"type":"object","required":["scans"],"properties":{"scans":{"type":"array","items":{"type":"object","required":["id","projectId","status","totalJobs","completedJobs","failedJobs","durationMs","triggeredBy","startedAt","finishedAt","createdAt","updatedAt","jobCounts","engineOutcomes","dispatchReadiness","exampleAnswerCount","analysisErrorCount","consentBlockedCount"],"properties":{"id":{"type":"string"},"projectId":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","partial","failed"]},"totalJobs":{"type":"integer"},"completedJobs":{"type":"integer"},"failedJobs":{"type":"integer"},"durationMs":{"type":["integer","null"]},"triggeredBy":{"type":"string","enum":["cron","user","agent","proof"]},"startedAt":{"type":["string","null"],"format":"date-time"},"finishedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"jobCounts":{"type":"object","required":["pending","queued","running","succeeded","failed","unknown"],"properties":{"pending":{"type":"integer"},"queued":{"type":"integer"},"running":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"unknown":{"type":"integer"}}},"engineOutcomes":{"anyOf":[{"type":"array","items":{"type":"object","required":["engine","status","count"],"properties":{"engine":{"$ref":"#/components/schemas/Engine"},"status":{"type":"string","enum":["pending","queued","running","succeeded","failed","unknown"]},"count":{"type":"integer"}}}},{"type":"null"}],"description":"Recorded per-engine job states when all scan jobs have engine details; null for incomplete legacy evidence. Succeeded means collected, not necessarily analyzed."},"dispatchReadiness":{"type":"object","required":["ready","reason"],"properties":{"ready":{"type":"boolean"},"reason":{"type":["string","null"]}}},"exampleAnswerCount":{"type":"integer"},"analysisErrorCount":{"type":"integer"},"consentBlockedCount":{"type":"integer"}}}}}},"AnswerQuotaData":{"type":"object","required":["quota"],"properties":{"quota":{"type":"object","required":["period","limit","used","held","remaining"],"properties":{"period":{"type":"string","format":"date"},"limit":{"type":"integer"},"used":{"type":"integer"},"held":{"type":"integer"},"remaining":{"type":"integer"}}}}},"AnswerCost":{"type":"object","required":["fingerprint","plannedAnswers","quota"],"properties":{"fingerprint":{"type":"string"},"plannedAnswers":{"type":"integer"},"quota":{"type":"object","required":["period","limit","used","held","remaining","plannedAnswers","remainingAfter"],"properties":{"period":{"type":"string","format":"date"},"limit":{"type":"integer"},"used":{"type":"integer"},"held":{"type":"integer"},"remaining":{"type":"integer"},"plannedAnswers":{"type":"integer"},"remainingAfter":{"type":"integer"}}}}},"ProofCost":{"type":"object","required":["plannedAnswers","immediateDueAnswers","quota","checkpoints"],"properties":{"plannedAnswers":{"type":"integer"},"immediateDueAnswers":{"type":"integer"},"quota":{"type":"object","required":["period","limit","used","held","remaining","immediateDueAnswers","remainingAfter"],"properties":{"period":{"type":"string","format":"date"},"limit":{"type":"integer"},"used":{"type":"integer"},"held":{"type":"integer"},"remaining":{"type":"integer"},"immediateDueAnswers":{"type":"integer"},"remainingAfter":{"type":"integer"}}},"checkpoints":{"type":"array","items":{"type":"object","required":["offsetDays","dueAt","plannedAnswers"],"properties":{"offsetDays":{"type":"integer","enum":[7,14,30]},"dueAt":{"type":"string","format":"date-time"},"plannedAnswers":{"type":"integer"}}}}}},"ProofMeasurement":{"type":"object","required":["id","proofId","projectId","offsetDays","engine","dueAt","baselineRunId","scanId","runId","verdictBefore","verdictAfter","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"proofId":{"type":"string"},"projectId":{"type":"string"},"offsetDays":{"type":"integer","enum":[7,14,30]},"engine":{"$ref":"#/components/schemas/Engine"},"dueAt":{"type":"string","format":"date-time"},"baselineRunId":{"type":"string"},"scanId":{"type":["string","null"]},"runId":{"type":["string","null"]},"verdictBefore":{"$ref":"#/components/schemas/Verdict"},"verdictAfter":{"type":["string","null"],"enum":["strong","cited","retrieved","mentioned_only","invisible",null]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ProofCheckpoint":{"type":"object","required":["offsetDays","dueAt","lifecycle","outcome","engines"],"properties":{"offsetDays":{"type":"integer","enum":[7,14,30]},"dueAt":{"type":["string","null"],"format":"date-time"},"lifecycle":{"type":"string","enum":["pending","due","running","finished"]},"outcome":{"type":["string","null"],"enum":["measured","disproven","inconclusive",null]},"engines":{"type":"array","items":{"type":"object","required":["id","proofId","projectId","offsetDays","engine","dueAt","baselineRunId","scanId","runId","verdictBefore","verdictAfter","createdAt","updatedAt","jobStatus","comparison"],"properties":{"id":{"type":"string"},"proofId":{"type":"string"},"projectId":{"type":"string"},"offsetDays":{"type":"integer","enum":[7,14,30]},"engine":{"$ref":"#/components/schemas/Engine"},"dueAt":{"type":"string","format":"date-time"},"baselineRunId":{"type":"string"},"scanId":{"type":["string","null"]},"runId":{"type":["string","null"]},"verdictBefore":{"$ref":"#/components/schemas/Verdict"},"verdictAfter":{"type":["string","null"],"enum":["strong","cited","retrieved","mentioned_only","invisible",null]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"jobStatus":{"type":["string","null"],"enum":["pending","queued","running","succeeded","failed","unknown",null]},"comparison":{"type":"object","required":["outcome","delta"],"properties":{"outcome":{"type":"string","enum":["measured","disproven","inconclusive"]},"delta":{"type":["integer","null"]}}}}}}}},"ProofReceipt":{"type":"object","required":["run","prompt","grounded","mentions","citations","queries"],"properties":{"run":{"type":"object","required":["id","promptId","projectId","scanId","scanJobId","engine","collectionMethod","answerOrigin","modelVersion","verdict","yourPosition","rawResponse","promptText","citedBrands","mentions","citationCount","searchQueryCount","latencyMs","success","error","analysisError","runAt"],"properties":{"id":{"type":"string"},"promptId":{"type":"string"},"projectId":{"type":"string"},"scanId":{"type":["string","null"]},"scanJobId":{"type":["string","null"]},"engine":{"$ref":"#/components/schemas/Engine"},"collectionMethod":{"type":"string","enum":["api","scrape","vendor_api"]},"answerOrigin":{"type":["string","null"],"enum":["provider","fixture",null],"description":"Trusted provider path, explicit fixture, or unknown legacy origin; separate from collection method."},"modelVersion":{"type":["string","null"]},"verdict":{"type":["string","null"],"enum":["strong","cited","retrieved","mentioned_only","invisible",null]},"yourPosition":{"type":["integer","null"]},"rawResponse":{"type":["string","null"]},"promptText":{"type":["string","null"]},"citedBrands":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"mentions":{"anyOf":[{"type":"array","items":{"type":"object","additionalProperties":true}},{"type":"null"}]},"citationCount":{"type":"integer"},"searchQueryCount":{"type":["integer","null"]},"latencyMs":{"type":["integer","null"]},"success":{"type":"boolean"},"error":{"type":["string","null"]},"analysisError":{"type":["string","null"]},"runAt":{"type":"string","format":"date-time"}}},"prompt":{"type":"object","required":["id","projectId","text","intent","engines","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"projectId":{"type":"string"},"text":{"type":"string"},"intent":{"type":["string","null"]},"engines":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/Engine"}},{"type":"null"}]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"grounded":{"type":"boolean"},"mentions":{"type":"array","items":{"type":"object","required":["id","runId","projectId","competitorId","brand","brandKind","position","sentiment","quotedPassage","createdAt"],"properties":{"id":{"type":"string"},"runId":{"type":"string"},"projectId":{"type":"string"},"competitorId":{"type":["string","null"]},"brand":{"type":"string"},"brandKind":{"type":"string"},"position":{"type":["integer","null"]},"sentiment":{"type":["string","null"]},"quotedPassage":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}}},"citations":{"type":"array","items":{"type":"object","required":["id","runId","projectId","url","domain","title","position","kind","isYours","createdAt"],"properties":{"id":{"type":"string"},"runId":{"type":"string"},"projectId":{"type":"string"},"url":{"type":"string"},"domain":{"type":"string"},"title":{"type":["string","null"]},"position":{"type":["integer","null"]},"kind":{"type":"string","enum":["cited","retrieved"]},"isYours":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}}},"queries":{"type":"array","items":{"type":"object","required":["id","runId","projectId","query","queryType","count","createdAt"],"properties":{"id":{"type":"string"},"runId":{"type":"string"},"projectId":{"type":"string"},"query":{"type":"string"},"queryType":{"type":"string"},"count":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}}}}},"Proof":{"type":"object","required":["id","projectId","promptId","promptText","whatChanged","url","changeKind","changedAt","consentQuoteFingerprint","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"projectId":{"type":"string"},"promptId":{"type":"string"},"promptText":{"type":"string"},"whatChanged":{"type":"string"},"url":{"type":"string"},"changeKind":{"type":"string","enum":["content","schema","backlink","distribution"]},"changedAt":{"type":"string","format":"date-time"},"consentQuoteFingerprint":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ProofSummary":{"type":"object","required":["id","projectId","promptId","promptText","whatChanged","url","changeKind","changedAt","consentQuoteFingerprint","createdAt","updatedAt","status","lifecycle","currentOffsetDays","checkpoints"],"properties":{"id":{"type":"string"},"projectId":{"type":"string"},"promptId":{"type":"string"},"promptText":{"type":"string"},"whatChanged":{"type":"string"},"url":{"type":"string"},"changeKind":{"type":"string","enum":["content","schema","backlink","distribution"]},"changedAt":{"type":"string","format":"date-time"},"consentQuoteFingerprint":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","measured","disproven","inconclusive"]},"lifecycle":{"type":"string","enum":["pending","due","running","finished"]},"currentOffsetDays":{"type":"integer","enum":[7,14,30]},"checkpoints":{"type":"array","items":{"$ref":"#/components/schemas/ProofCheckpoint"}}}},"ProofDetail":{"type":"object","required":["id","projectId","promptId","promptText","whatChanged","url","changeKind","changedAt","consentQuoteFingerprint","createdAt","updatedAt","status","lifecycle","currentOffsetDays","checkpoints","receipts","priorScans"],"properties":{"id":{"type":"string"},"projectId":{"type":"string"},"promptId":{"type":"string"},"promptText":{"type":"string"},"whatChanged":{"type":"string"},"url":{"type":"string"},"changeKind":{"type":"string","enum":["content","schema","backlink","distribution"]},"changedAt":{"type":"string","format":"date-time"},"consentQuoteFingerprint":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","measured","disproven","inconclusive"]},"lifecycle":{"type":"string","enum":["pending","due","running","finished"]},"currentOffsetDays":{"type":"integer","enum":[7,14,30]},"checkpoints":{"type":"array","items":{"$ref":"#/components/schemas/ProofCheckpoint"}},"receipts":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ProofReceipt"}},"priorScans":{"type":"array","items":{"type":"object","required":["id","projectId","measurementId","previousScanId","createdAt"],"properties":{"id":{"type":"string"},"projectId":{"type":"string"},"measurementId":{"type":"string"},"previousScanId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}},"ProofPreviewData":{"type":"object","required":["promptId","promptText","fingerprint","baselines","cost"],"properties":{"promptId":{"type":"string"},"promptText":{"type":"string"},"fingerprint":{"type":"string"},"baselines":{"type":"array","items":{"type":"object","required":["runId","engine","verdict","runAt","collectionMethod"],"properties":{"runId":{"type":"string"},"engine":{"$ref":"#/components/schemas/Engine"},"verdict":{"$ref":"#/components/schemas/Verdict"},"runAt":{"type":"string","format":"date-time"},"collectionMethod":{"type":"string","enum":["api","scrape","vendor_api"]}}}},"cost":{"$ref":"#/components/schemas/ProofCost"}}},"ProofCreateData":{"type":"object","required":["proof","measurements","cost"],"properties":{"proof":{"$ref":"#/components/schemas/Proof"},"measurements":{"type":"array","items":{"$ref":"#/components/schemas/ProofMeasurement"}},"cost":{"$ref":"#/components/schemas/ProofCost"}}},"ProofListData":{"type":"object","required":["proofs"],"properties":{"proofs":{"type":"array","items":{"$ref":"#/components/schemas/ProofSummary"}}}},"ProofDetailData":{"type":"object","required":["proof"],"properties":{"proof":{"$ref":"#/components/schemas/ProofDetail"}}},"ProofBatchData":{"type":"object","required":["proofs"],"properties":{"proofs":{"type":"array","items":{"type":"object","required":["proofId","proof"],"properties":{"proofId":{"type":"string"},"proof":{"anyOf":[{"$ref":"#/components/schemas/ProofDetail"},{"type":"null"}]}}}}}},"ProofMeasureData":{"type":"object","required":["started","reused","skipped","cost"],"properties":{"started":{"type":"array","items":{"type":"object","required":["measurementId","scanId"],"properties":{"measurementId":{"type":"string"},"scanId":{"type":"string"}}}},"reused":{"type":"array","items":{"type":"object","required":["measurementId","scanId"],"properties":{"measurementId":{"type":"string"},"scanId":{"type":"string"}}}},"skipped":{"type":"array","items":{"type":"object","required":["measurementId","reason"],"properties":{"measurementId":{"type":"string"},"reason":{"type":"string"}}}},"cost":{"type":"object","required":["plannedAnswers","immediateDueAnswers","scans"],"properties":{"plannedAnswers":{"type":"integer"},"immediateDueAnswers":{"type":"integer"},"scans":{"type":"array","items":{"$ref":"#/components/schemas/AnswerCost"}}}}}},"ProofConsentData":{"type":"object","required":["fingerprint","plannedAnswers","immediateDueAnswers","quota","consentCurrent","recoverable"],"properties":{"fingerprint":{"type":"string"},"plannedAnswers":{"type":"integer"},"immediateDueAnswers":{"type":"integer"},"quota":{"type":"object","required":["period","limit","used","held","remaining","remainingAfter"],"properties":{"period":{"type":"string","format":"date"},"limit":{"type":"integer"},"used":{"type":"integer"},"held":{"type":"integer"},"remaining":{"type":"integer"},"remainingAfter":{"type":"integer"}}},"consentCurrent":{"type":"boolean"},"recoverable":{"type":"array","items":{"type":"object","required":["measurementId","scanId"],"properties":{"measurementId":{"type":"string"},"scanId":{"type":"string"}}}}}},"CadencePreviewData":{"type":"object","required":["frequency","fingerprint","plannedAnswers","engines","monthlyAnswers","weeklySlot","skipped","cost"],"properties":{"frequency":{"type":"string","enum":["daily","weekly","monthly"]},"fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"plannedAnswers":{"type":"integer"},"engines":{"type":"array","items":{"type":"object","required":["engine","frequency","plannedAnswers","monthlyAnswers"],"properties":{"engine":{"$ref":"#/components/schemas/Engine"},"frequency":{"type":"string","enum":["daily","weekly","monthly"]},"plannedAnswers":{"type":"integer"},"monthlyAnswers":{"type":"integer"}}}},"monthlyAnswers":{"type":"integer","description":"Most answers the schedule can use in a 31-day month: daily engines 31 runs, weekly 5, every 30 days 2."},"weeklySlot":{"anyOf":[{"type":"object","required":["weekday","hourUtc"],"properties":{"weekday":{"type":"string","enum":["sunday","monday","tuesday","wednesday","thursday","friday","saturday"]},"hourUtc":{"type":"integer"}}},{"type":"null"}],"description":"When a plan runs some engines weekly on a daily schedule: their weekly window opens at this UTC weekday and hour and lasts 24 hours."},"skipped":{"type":"array","items":{"type":"object","required":["promptId","engine"],"properties":{"promptId":{"type":"string"},"engine":{"$ref":"#/components/schemas/Engine"}}}},"cost":{"$ref":"#/components/schemas/AnswerCost"}}},"CadenceStatusData":{"type":"object","required":["receiver","status","frequency","plannedAnswers","engines","monthlyAnswers","weeklySlot","consentedAnswers","consentedEngines","pendingEngines","schedulerJobLimit","schedulerCapacitySufficient","eligibility","nextEligibleAt","nextWeeklyAt","allowanceSufficient","schedulerDelivery"],"properties":{"receiver":{"type":"object","required":["state","lastOutcome","lastReceivedAt","lastFinishedAt","lastCompletedAt"],"properties":{"state":{"type":"string","enum":["unverified","recent","stale","incomplete","failed"]},"lastOutcome":{"type":["string","null"],"enum":["running","completed","failed",null]},"lastReceivedAt":{"type":["string","null"],"format":"date-time"},"lastFinishedAt":{"type":["string","null"],"format":"date-time"},"lastCompletedAt":{"type":["string","null"],"format":"date-time"}}},"status":{"type":"string","enum":["active","disabled","changed"]},"frequency":{"type":"string","enum":["daily","weekly","monthly"]},"plannedAnswers":{"type":"integer"},"engines":{"type":"array","items":{"type":"object","required":["engine","frequency","plannedAnswers","monthlyAnswers"],"properties":{"engine":{"$ref":"#/components/schemas/Engine"},"frequency":{"type":"string","enum":["daily","weekly","monthly"]},"plannedAnswers":{"type":"integer"},"monthlyAnswers":{"type":"integer"}}}},"monthlyAnswers":{"type":"integer","description":"Most answers the schedule can use in a 31-day month: daily engines 31 runs, weekly 5, every 30 days 2."},"weeklySlot":{"anyOf":[{"type":"object","required":["weekday","hourUtc"],"properties":{"weekday":{"type":"string","enum":["sunday","monday","tuesday","wednesday","thursday","friday","saturday"]},"hourUtc":{"type":"integer"}}},{"type":"null"}],"description":"When a plan runs some engines weekly on a daily schedule: their weekly window opens at this UTC weekday and hour and lasts 24 hours."},"consentedAnswers":{"type":["integer","null"]},"consentedEngines":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/Engine"}},{"type":"null"}],"description":"Engines the active consent covers. After a plan change this can be fewer than the plan runs; only these run until the customer confirms again."},"pendingEngines":{"type":"array","items":{"$ref":"#/components/schemas/Engine"},"description":"Plan engines not yet covered by the consent. They do not run until the customer previews and confirms again."},"schedulerJobLimit":{"type":"integer"},"schedulerCapacitySufficient":{"type":"boolean"},"eligibility":{"type":"string","enum":["paused","due","waiting"]},"nextEligibleAt":{"type":["string","null"],"format":"date-time"},"nextWeeklyAt":{"type":["string","null"],"format":"date-time"},"allowanceSufficient":{"type":["boolean","null"]},"schedulerDelivery":{"const":"unverified"}}},"CadenceUpdateData":{"oneOf":[{"type":"object","required":["enabled"],"properties":{"enabled":{"const":false}}},{"type":"object","required":["enabled","frequency","plannedAnswers"],"properties":{"enabled":{"const":true},"frequency":{"type":"string","enum":["daily","weekly","monthly"]},"plannedAnswers":{"type":"integer"}}}]},"ApiEnvelope":{"type":"object","required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false,"properties":{"ok":{"const":true},"data":{},"agent_guidance":{"type":"string"},"_meta":{"type":"object","additionalProperties":true},"_human":{"type":"string"}}},"ErrorEnvelope":{"type":"object","required":["ok","data","agent_guidance","_meta","_human"],"additionalProperties":false,"properties":{"ok":{"const":false},"data":{"type":"object","required":["code"],"additionalProperties":false,"properties":{"code":{"type":"string"}}},"agent_guidance":{"type":"string"},"_meta":{"type":"object","additionalProperties":true},"_human":{"type":"string"}}},"WhoamiResponse":{"type":"object","required":["user","orgId"],"additionalProperties":false,"properties":{"user":{"oneOf":[{"type":"null"},{"type":"object","required":["id","email"],"additionalProperties":false,"properties":{"id":{"type":"string"},"email":{"type":["string","null"]}}}]},"orgId":{"type":["string","null"]}}},"VisibilityAnalytics":{"type":"object","description":"Opt-in exact-window analytics, separate from latest100/20 detail samples. Adjacent equal-length half-open UTC windows (N×24h for a preset, whole UTC days for a finished custom range) use runAt recording time; delayed recovery may change the recording period. Current labels apply to both periods; historical own identities are retained. Closed-world recognized-brand share is not share of all brands. Known evidence rates expose their own denominators and unknown counts. Unknown source provenance suppresses source totals. Truncation suppresses affected period metrics and deltas; coverage counts then describe observed lower bounds. No planned coverage or like-for-like/causal claim. asOf freezes boundaries only, not late inserts or label changes.","required":["status","asOf","sentiment"],"properties":{"status":{"enum":["available","unavailable"]},"reason":{"enum":["unbounded_range","unsupported_range","range_in_progress"]},"periodDays":{"type":"integer","minimum":1,"description":"Length in days of the current and of the previous period."},"asOf":{"type":"string","format":"date-time"},"timezone":{"const":"UTC"},"timestampBasis":{"const":"answer_recorded_at"},"comparisonBasis":{"const":"recorded_window_samples"},"comparability":{"const":"not_established"},"labelClassification":{"const":"current_question_labels"},"answerOriginPolicy":{"const":"exclude_fixture_include_unknown"},"explanation":{"type":"string"},"filters":{"type":"object","properties":{"engine":{"type":["string","null"]},"topic":{"type":"string"},"branded":{"type":"string"}}},"current":{"type":"object","required":["startInclusive","endExclusive","status","queryComplete","bounds","coverage","metrics"],"properties":{"startInclusive":{"type":"string","format":"date-time"},"endExclusive":{"type":"string","format":"date-time"},"status":{"enum":["measured","no_data","truncated"]},"queryComplete":{"type":"boolean"},"bounds":{"type":"object","properties":{"runLimit":{"const":10000},"evidenceRowLimit":{"const":100000}}},"metrics":{"type":"object","required":["textMentionRate","recognizedBrandShare","ownCitationRate","ownRetrievalRate","ownCitedSources","ownRetrievedSources"],"properties":{"textMentionRate":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"recognizedBrandShare":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownCitationRate":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownRetrievalRate":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownCitedSources":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownRetrievedSources":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}}}},"coverage":{"type":"object","properties":{"recordedRuns":{"type":"integer","minimum":0},"evidenceRows":{"type":"integer","minimum":0},"analyzedGroundedRuns":{"type":"integer","minimum":0},"failedRuns":{"type":"integer","minimum":0},"analysisErrorRuns":{"type":"integer","minimum":0},"missingAnswerRuns":{"type":"integer","minimum":0},"unknownOriginRuns":{"type":"integer","minimum":0},"unknownNameEvidence":{"type":"integer","minimum":0},"unknownBrandEvidence":{"type":"integer","minimum":0},"unknownSourceEvidence":{"type":"integer","minimum":0},"distinctPrompts":{"type":"integer","minimum":0},"countBasis":{"enum":["exact","observed_lower_bound"]},"plannedAnswerCount":{"type":"null"},"plannedCoverage":{"type":"null"},"coverageBasis":{"const":"recorded_answers_only"},"minRecordedAt":{"type":["string","null"],"format":"date-time"},"maxRecordedAt":{"type":["string","null"],"format":"date-time"},"mix":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string"},"collectionMethod":{"type":"string"},"modelVersion":{"type":["string","null"]},"recordedRuns":{"type":"integer"},"analyzedRuns":{"type":"integer"}}}}}}}},"previous":{"type":"object","required":["startInclusive","endExclusive","status","queryComplete","bounds","coverage","metrics"],"properties":{"startInclusive":{"type":"string","format":"date-time"},"endExclusive":{"type":"string","format":"date-time"},"status":{"enum":["measured","no_data","truncated"]},"queryComplete":{"type":"boolean"},"bounds":{"type":"object","properties":{"runLimit":{"const":10000},"evidenceRowLimit":{"const":100000}}},"metrics":{"type":"object","required":["textMentionRate","recognizedBrandShare","ownCitationRate","ownRetrievalRate","ownCitedSources","ownRetrievedSources"],"properties":{"textMentionRate":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"recognizedBrandShare":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownCitationRate":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownRetrievalRate":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownCitedSources":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownRetrievedSources":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}}}},"coverage":{"type":"object","properties":{"recordedRuns":{"type":"integer","minimum":0},"evidenceRows":{"type":"integer","minimum":0},"analyzedGroundedRuns":{"type":"integer","minimum":0},"failedRuns":{"type":"integer","minimum":0},"analysisErrorRuns":{"type":"integer","minimum":0},"missingAnswerRuns":{"type":"integer","minimum":0},"unknownOriginRuns":{"type":"integer","minimum":0},"unknownNameEvidence":{"type":"integer","minimum":0},"unknownBrandEvidence":{"type":"integer","minimum":0},"unknownSourceEvidence":{"type":"integer","minimum":0},"distinctPrompts":{"type":"integer","minimum":0},"countBasis":{"enum":["exact","observed_lower_bound"]},"plannedAnswerCount":{"type":"null"},"plannedCoverage":{"type":"null"},"coverageBasis":{"const":"recorded_answers_only"},"minRecordedAt":{"type":["string","null"],"format":"date-time"},"maxRecordedAt":{"type":["string","null"],"format":"date-time"},"mix":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string"},"collectionMethod":{"type":"string"},"modelVersion":{"type":["string","null"]},"recordedRuns":{"type":"integer"},"analyzedRuns":{"type":"integer"}}}}}}}},"changes":{"type":"object","required":["textMentionRate","recognizedBrandShare","ownCitationRate","ownRetrievalRate","ownCitedSources","ownRetrievedSources"],"properties":{"textMentionRate":{"type":"object","properties":{"value":{"type":["number","null"]},"unit":{"enum":["percentage_points","sources"]},"reason":{"type":["string","null"]}}},"recognizedBrandShare":{"type":"object","properties":{"value":{"type":["number","null"]},"unit":{"enum":["percentage_points","sources"]},"reason":{"type":["string","null"]}}},"ownCitationRate":{"type":"object","properties":{"value":{"type":["number","null"]},"unit":{"enum":["percentage_points","sources"]},"reason":{"type":["string","null"]}}},"ownRetrievalRate":{"type":"object","properties":{"value":{"type":["number","null"]},"unit":{"enum":["percentage_points","sources"]},"reason":{"type":["string","null"]}}},"ownCitedSources":{"type":"object","properties":{"value":{"type":["number","null"]},"unit":{"enum":["percentage_points","sources"]},"reason":{"type":["string","null"]}}},"ownRetrievedSources":{"type":"object","properties":{"value":{"type":["number","null"]},"unit":{"enum":["percentage_points","sources"]},"reason":{"type":["string","null"]}}}}},"engines":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string"},"current":{"type":"object","required":["startInclusive","endExclusive","status","queryComplete","bounds","coverage","metrics"],"properties":{"startInclusive":{"type":"string","format":"date-time"},"endExclusive":{"type":"string","format":"date-time"},"status":{"enum":["measured","no_data","truncated"]},"queryComplete":{"type":"boolean"},"bounds":{"type":"object","properties":{"runLimit":{"const":10000},"evidenceRowLimit":{"const":100000}}},"metrics":{"type":"object","required":["textMentionRate","recognizedBrandShare","ownCitationRate","ownRetrievalRate","ownCitedSources","ownRetrievedSources"],"properties":{"textMentionRate":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"recognizedBrandShare":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownCitationRate":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownRetrievalRate":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownCitedSources":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownRetrievedSources":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}}}},"coverage":{"type":"object","properties":{"recordedRuns":{"type":"integer","minimum":0},"evidenceRows":{"type":"integer","minimum":0},"analyzedGroundedRuns":{"type":"integer","minimum":0},"failedRuns":{"type":"integer","minimum":0},"analysisErrorRuns":{"type":"integer","minimum":0},"missingAnswerRuns":{"type":"integer","minimum":0},"unknownOriginRuns":{"type":"integer","minimum":0},"unknownNameEvidence":{"type":"integer","minimum":0},"unknownBrandEvidence":{"type":"integer","minimum":0},"unknownSourceEvidence":{"type":"integer","minimum":0},"distinctPrompts":{"type":"integer","minimum":0},"countBasis":{"enum":["exact","observed_lower_bound"]},"plannedAnswerCount":{"type":"null"},"plannedCoverage":{"type":"null"},"coverageBasis":{"const":"recorded_answers_only"},"minRecordedAt":{"type":["string","null"],"format":"date-time"},"maxRecordedAt":{"type":["string","null"],"format":"date-time"},"mix":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string"},"collectionMethod":{"type":"string"},"modelVersion":{"type":["string","null"]},"recordedRuns":{"type":"integer"},"analyzedRuns":{"type":"integer"}}}}}}}},"previous":{"type":"object","required":["startInclusive","endExclusive","status","queryComplete","bounds","coverage","metrics"],"properties":{"startInclusive":{"type":"string","format":"date-time"},"endExclusive":{"type":"string","format":"date-time"},"status":{"enum":["measured","no_data","truncated"]},"queryComplete":{"type":"boolean"},"bounds":{"type":"object","properties":{"runLimit":{"const":10000},"evidenceRowLimit":{"const":100000}}},"metrics":{"type":"object","required":["textMentionRate","recognizedBrandShare","ownCitationRate","ownRetrievalRate","ownCitedSources","ownRetrievedSources"],"properties":{"textMentionRate":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"recognizedBrandShare":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownCitationRate":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownRetrievalRate":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownCitedSources":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}},"ownRetrievedSources":{"type":"object","required":["value","numerator","denominator","unknownCount","reason"],"properties":{"value":{"type":["number","null"]},"numerator":{"type":["number","null"]},"denominator":{"type":["number","null"]},"unknownCount":{"type":"integer"},"reason":{"type":["string","null"]}}}}},"coverage":{"type":"object","properties":{"recordedRuns":{"type":"integer","minimum":0},"evidenceRows":{"type":"integer","minimum":0},"analyzedGroundedRuns":{"type":"integer","minimum":0},"failedRuns":{"type":"integer","minimum":0},"analysisErrorRuns":{"type":"integer","minimum":0},"missingAnswerRuns":{"type":"integer","minimum":0},"unknownOriginRuns":{"type":"integer","minimum":0},"unknownNameEvidence":{"type":"integer","minimum":0},"unknownBrandEvidence":{"type":"integer","minimum":0},"unknownSourceEvidence":{"type":"integer","minimum":0},"distinctPrompts":{"type":"integer","minimum":0},"countBasis":{"enum":["exact","observed_lower_bound"]},"plannedAnswerCount":{"type":"null"},"plannedCoverage":{"type":"null"},"coverageBasis":{"const":"recorded_answers_only"},"minRecordedAt":{"type":["string","null"],"format":"date-time"},"maxRecordedAt":{"type":["string","null"],"format":"date-time"},"mix":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string"},"collectionMethod":{"type":"string"},"modelVersion":{"type":["string","null"]},"recordedRuns":{"type":"integer"},"analyzedRuns":{"type":"integer"}}}}}}}},"changes":{"type":"object","required":["textMentionRate","recognizedBrandShare","ownCitationRate","ownRetrievalRate","ownCitedSources","ownRetrievedSources"],"properties":{"textMentionRate":{"type":"object","properties":{"value":{"type":["number","null"]},"unit":{"enum":["percentage_points","sources"]},"reason":{"type":["string","null"]}}},"recognizedBrandShare":{"type":"object","properties":{"value":{"type":["number","null"]},"unit":{"enum":["percentage_points","sources"]},"reason":{"type":["string","null"]}}},"ownCitationRate":{"type":"object","properties":{"value":{"type":["number","null"]},"unit":{"enum":["percentage_points","sources"]},"reason":{"type":["string","null"]}}},"ownRetrievalRate":{"type":"object","properties":{"value":{"type":["number","null"]},"unit":{"enum":["percentage_points","sources"]},"reason":{"type":["string","null"]}}},"ownCitedSources":{"type":"object","properties":{"value":{"type":["number","null"]},"unit":{"enum":["percentage_points","sources"]},"reason":{"type":["string","null"]}}},"ownRetrievedSources":{"type":"object","properties":{"value":{"type":["number","null"]},"unit":{"enum":["percentage_points","sources"]},"reason":{"type":["string","null"]}}}}}}}},"sentiment":{"type":"object","properties":{"status":{"const":"not_analyzed"},"scope":{"const":"brand_in_answer"},"score":{"type":"null"},"method":{"type":"null"},"confidence":{"type":"null"},"reason":{"type":"string"}}}},"oneOf":[{"properties":{"status":{"const":"available"}},"required":["current","previous","changes","engines"]},{"properties":{"status":{"const":"unavailable"}},"required":["reason"]}]},"ProjectSummaryData":{"type":"object","additionalProperties":true,"description":"Recognized-brand evidence only; the current parser matches configured names/aliases, not every brand in an answer. Additive text-evidence fields preserve the established mentionRate denominator.","properties":{"analytics":{"$ref":"#/components/schemas/VisibilityAnalytics"},"project":{"type":"object","additionalProperties":true,"properties":{"updatedAt":{"type":"string","format":"date-time","description":"Last time project settings changed. Pass it as expectedUpdatedAt when updating settings so a stale edit is rejected with 409 revision_conflict."}}},"summary":{"type":"object","additionalProperties":true,"properties":{"mentionRate":{"type":"number","description":"Established rate: structured own-mention run IDs divided by all analyzed grounded runs; retained for compatibility."},"analyzedEngines":{"type":"array","items":{"type":"string"},"description":"Engines with analyzed grounded answers in the same recent 100-receipt window as runCount; distinct from configured engines."},"configuredAnswerCount":{"type":"integer","minimum":0,"description":"Prompt-engine checks in the current full-scan plan, including default engine selections; viewing this does not queue a scan."},"textMentionRate":{"type":["number","null"],"description":"Own textual-name rate over analyzed grounded runs with known name evidence; null when none have known evidence."},"brandEvidenceRunCount":{"type":"integer","minimum":0,"description":"Analyzed grounded runs whose stored name archives agree with structured mention names/counts. Missing, conflicting or partial records are uncovered. Dashboard SOV is unavailable unless this equals runCount."},"brandIdentityAmbiguous":{"type":"boolean","description":"True when a recorded name appears with different recorded identities; name-based comparisons are ambiguous."},"ambiguousBrandNames":{"type":"array","items":{"type":"string"},"description":"Recorded names associated with more than one kind or competitor ID in the selected answer window."},"textMentionRunCount":{"type":"integer","minimum":0,"description":"Known-name-evidence denominator of textMentionRate; may be smaller than runCount."}}},"filterScope":{"type":"object","description":"Present for filtered summaries. Source counts cover selected runs from the latest 100 non-example runs; unfiltered source counts cover all non-example history, including unknown origins.","properties":{"engine":{"type":["string","null"]},"range":{"type":"string","enum":["all","today","7d","14d","28d","30d","90d","custom"]},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"recentRunLimit":{"type":"integer","const":100},"sourceCounts":{"type":"string","const":"selected_recent_runs"},"runWindow":{"const":"latest_100_project_runs"},"returnedRunLimit":{"const":20},"labels":{"type":"object","properties":{"topic":{"type":"string","description":"Current topic: all, unknown, none (explicit no-topic), or value: followed by the exact literal topic. Applied within the latest 100 project runs.","anyOf":[{"enum":["all","unknown","none"]},{"pattern":"^value:[\\s\\S]+$","maxLength":206}]},"branded":{"type":"string","enum":["all","unknown","branded","unbranded"],"description":"Current user classification, including when selecting earlier answers."}}},"labelClassification":{"const":"current_question_labels"},"scanConfigurationCounts":{"const":"whole_project","description":"Only summary.configuredAnswerCount and summary.engines describe the full current scan configuration; label filtering does not shrink a quote or change consent."},"promptCountScope":{"const":"selected_active_questions"},"competitorCountScope":{"const":"whole_project"}}},"prompts":{"type":"array","description":"Saved questions with current user classifications and active status. Nullable labels are unknown; empty topic is explicit no-topic. Labels were not archived with earlier answers.","items":{"type":"object","required":["id","text","engines","topic","branded","isActive"],"properties":{"id":{"type":"string"},"text":{"type":"string"},"engines":{"type":["array","null"],"items":{"$ref":"#/components/schemas/Engine"}},"topic":{"type":["string","null"],"maxLength":200},"branded":{"type":["boolean","null"]},"isActive":{"type":"boolean"},"planPaused":{"type":"boolean","description":"Present only with plan enforcement on. True when this active question is above the workspace's plan question limit and is not scanned; questions are pooled across the workspace's websites."},"topicVolume":{"description":"Monthly AI search volume of the prompt's topic label, not of the prompt text (DataForSEO AI keyword data, US, English). Null when the topic is absent or not yet measured this month. bars: 0 for exactly 0, then 1 for 1-10, 2 for 11-100, 3 for 101-1,000, 4 for 1,001-10,000, 5 above 10,000.","anyOf":[{"type":"null"},{"type":"object","required":["topic","volume","bars","source","location","month"],"properties":{"topic":{"type":"string"},"volume":{"type":"integer","minimum":0},"bars":{"type":"integer","minimum":0,"maximum":5},"source":{"const":"dataforseo_ai"},"location":{"const":"US"},"month":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}$"}}}]},"difficulty":{"description":"Google keyword difficulty (0 to 100, DataForSEO Labs, US, English) of the prompt's topic label, not of the prompt text, from the latest cached month. Null when the topic is absent or not yet measured.","anyOf":[{"type":"null"},{"type":"object","required":["value","month"],"properties":{"value":{"type":"integer","minimum":0,"maximum":100},"month":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}$"}}}]}}}},"competitors":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"recordedMentions":{"type":"integer","minimum":0,"description":"Recorded mentions explicitly linked to this competitor ID, not a count of all answers assessing it."}}}},"runs":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"brandEvidenceComplete":{"type":"boolean","description":"True only for an analyzed grounded run whose complete saved name archive agrees with structured mention names/counts. Required evidence gate for exact name-count comparisons."},"answerOrigin":{"type":["string","null"],"enum":["provider","fixture",null],"description":"Trusted provider path or unknown legacy origin; known fixtures are excluded from ordinary summaries."},"recordedPromptText":{"type":["string","null"],"description":"Question wording recorded with this run, or null when the original wording is unavailable."},"recognizedBrands":{"type":["array","null"],"items":{"type":"string"},"description":"Recognized names when archive and structured evidence are complete; null when unavailable."},"recognizedCompetitorIds":{"type":["array","null"],"items":{"type":"string"},"description":"Explicit stored competitor IDs in complete analyzed evidence; a missing ID does not establish that the competitor was assessed."},"mentionedYou":{"type":["boolean","null"],"description":"Stored textual own-brand evidence; source citation/retrieval alone never means true. Null for missing archival evidence or unresolved runs."}}}}}},"ProjectSummaryBatchData":{"type":"object","properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSummaryData"}}}},"Engine":{"type":"string","enum":["chatgpt","perplexity","gemini","claude","copilot","google_aio","grok","deepseek"]},"Verdict":{"type":"string","enum":["strong","cited","retrieved","mentioned_only","invisible"]}}}}