{"openapi":"3.1.0","info":{"title":"Search for Agents Content API","version":"1.4.0","description":"An encyclopedia on search for agents"},"servers":[{"url":"https://www.searchforagents.com"}],"paths":{"/api/v1/content":{"get":{"summary":"List, search, and filter public field notes","parameters":[{"name":"q","in":"query","description":"Weighted full-content search query.","schema":{"type":"string"}},{"name":"topic","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"include","in":"query","description":"Set to quality to include the full deterministic quality report.","schema":{"type":"string","enum":["quality"]}}],"responses":{"200":{"description":"Paginated public content results","headers":{"ETag":{"schema":{"type":"string"}},"Last-Modified":{"schema":{"type":"string"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentResults"}}}},"304":{"description":"The representation has not changed."},"429":{"description":"The shared request limit was exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Distributed rate limiting is not configured in production.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_content","description":"List, search, and filter public field notes"}},"/api/v1/content/{id}":{"get":{"summary":"Retrieve one public field note by stable content ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^post_[a-z0-9_-]+$"}}],"responses":{"200":{"description":"Complete public content document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentDocument"}}}},"304":{"description":"The representation has not changed."},"404":{"description":"No public content has this ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_content_id","description":"Retrieve one public field note by stable content ID"}},"/api/v1/search":{"get":{"summary":"Search public field notes with weighted full-content ranking","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"topic","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Ranked public content results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentResults"}}}},"304":{"description":"The representation has not changed."},"429":{"description":"The shared request limit was exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Distributed rate limiting is not configured in production.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_search","description":"Search public field notes with weighted full-content ranking"}},"/api/v1/topics":{"get":{"summary":"List public topics and their content counts","responses":{"200":{"description":"Public topic index","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"get_api_v1_topics","description":"List public topics and their content counts"}},"/api/v1/authors":{"get":{"summary":"List public author profiles and their content counts","responses":{"200":{"description":"Public author index","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"get_api_v1_authors","description":"List public author profiles and their content counts"}},"/api/v1/updated-since":{"get":{"summary":"List public field notes updated after a date","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Content updated after the supplied date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentResults"}}}},"400":{"description":"Missing or invalid date.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_updated_since","description":"List public field notes updated after a date"}},"/api/v1/sources":{"get":{"summary":"List sources cited by public field notes","parameters":[{"name":"publisher","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}],"responses":{"200":{"description":"Deduplicated public citation sources."}},"operationId":"get_api_v1_sources","description":"List sources cited by public field notes"}},"/api/v1/content/{id}/related":{"get":{"summary":"Find related public field notes","description":"Uses deterministic topic and tag overlap, not embeddings or vector search.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^post_[a-z0-9_-]+$"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":5}}],"responses":{"200":{"description":"Related public field notes with relationship evidence."},"404":{"description":"Public content was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_content_id_related"}},"/api/v1/topics/{slug}/updates":{"get":{"summary":"Poll public updates for one topic","description":"Read-only polling descriptor; this endpoint does not store subscriber data or promise delivery.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"date","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Public topic updates and polling metadata."},"400":{"description":"Invalid date.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Topic not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_topics_slug_updates"}},"/api/v1/changes":{"get":{"summary":"Read the versioned public change feed","description":"Deterministic public-only events ordered by date and stable content ID. Cursors contain no visitor or subscriber data.","parameters":[{"name":"cursor","in":"query","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Public change events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeFeed"}}}},"304":{"description":"The feed has not changed."},"400":{"description":"Invalid cursor or limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Distributed rate limiting is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_changes"}},"/api/v1/topics/{slug}/changes":{"get":{"summary":"Read public changes for one topic","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Topic-filtered public change events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeFeed"}}}},"400":{"description":"Invalid cursor or limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Topic not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_topics_slug_changes","description":"Read public changes for one topic"}},"/api/v1/research":{"get":{"summary":"List reviewed public research pages","responses":{"200":{"description":"Research index.","content":{"application/json":{"schema":{"type":"object","required":["count","records"],"properties":{"count":{"type":"integer"},"records":{"type":"array","items":{"$ref":"#/components/schemas/AdvancedContentSummary"}}}}}}}},"operationId":"get_api_v1_research","description":"List reviewed public research pages"}},"/api/v1/research/{id}":{"get":{"summary":"Retrieve one reviewed research page","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^research_[a-z0-9_-]+$"}}],"responses":{"200":{"description":"Research document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvancedContentDocument"}}}},"404":{"description":"Research page not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_research_id","description":"Retrieve one reviewed research page"}},"/api/v1/datasets":{"get":{"summary":"List versioned public datasets","responses":{"200":{"description":"Dataset index.","content":{"application/json":{"schema":{"type":"object","required":["count","records"],"properties":{"count":{"type":"integer"},"records":{"type":"array","items":{"$ref":"#/components/schemas/AdvancedContentSummary"}}}}}}}},"operationId":"get_api_v1_datasets","description":"List versioned public datasets"}},"/api/v1/datasets/{id}":{"get":{"summary":"Retrieve one versioned public dataset","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^dataset_[a-z0-9_-]+$"}}],"responses":{"200":{"description":"Dataset document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvancedContentDocument"}}}},"404":{"description":"Dataset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_datasets_id","description":"Retrieve one versioned public dataset"}},"/api/v1/content/{id}/source-bundle":{"get":{"summary":"Retrieve public provenance and source metadata","description":"Reports repository content integrity and editorial source metadata; it does not claim source archiving or current reachability.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Public source bundle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceBundle"}}}},"404":{"description":"Source bundle not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_content_id_source_bundle"}},"/api/v1/topic-subscriptions":{"get":{"summary":"List owned webhook subscriptions","security":[{"AgentBearer":[]}],"responses":{"200":{"description":"Owner-isolated subscriptions without secret material.","content":{"application/json":{"schema":{"type":"object","required":["count","subscriptions"],"properties":{"count":{"type":"integer"},"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/TopicSubscription"}}}}}}},"401":{"description":"Bearer credential required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"subscription:read required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Authentication or Redis unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_topic_subscriptions","description":"List owned webhook subscriptions"},"post":{"summary":"Create a topic webhook subscription","description":"Requires subscription:write. The subscriber supplies a signing secret that is encrypted at rest and never returned.","security":[{"AgentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTopicSubscription"}}}},"responses":{"201":{"description":"Subscription created.","content":{"application/json":{"schema":{"type":"object","required":["subscription"],"properties":{"subscription":{"$ref":"#/components/schemas/TopicSubscription"}}}}}},"400":{"description":"Invalid topic, endpoint, or request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Bearer credential required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"subscription:write required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Authentication, encryption, or Redis unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"post_api_v1_topic_subscriptions"}},"/api/v1/topic-subscriptions/{id}":{"delete":{"summary":"Delete an owned webhook subscription","security":[{"AgentBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^sub_[a-f0-9]{32}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"200":{"description":"Subscription deleted."},"404":{"description":"Owned subscription not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"delete_api_v1_topic_subscriptions_id","description":"Delete an owned webhook subscription"}},"/api/mcp":{"post":{"summary":"Stateless Streamable HTTP MCP endpoint","description":"Anonymous clients receive public read tools. Valid scoped bearer credentials add only explicitly authorized proposal tools. JSON-RPC batches are rejected.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"One MCP JSON-RPC request or notification."}}}},"responses":{"200":{"description":"MCP JSON response; no session state is issued."},"400":{"description":"Malformed, invalid, or batched JSON-RPC request."},"401":{"description":"Supplied bearer credential is invalid."},"403":{"description":"Host or origin is not allowed."},"405":{"description":"Only POST is supported."},"413":{"description":"Request exceeds 256 KB."},"415":{"description":"Content-Type must be application/json."},"429":{"description":"Distributed request limit exceeded."},"503":{"description":"Configured authentication or distributed limiting is unavailable."}},"operationId":"post_api_mcp"}},"/api/v1/intelligence":{"get":{"summary":"Build a deterministic public-content intelligence report","description":"Requires intelligence:read. Uses no network, model, embedding, or vector calls.","security":[{"AgentBearer":[]}],"parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Versioned graph and bounded editorial recommendations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelligenceReport"}}}},"400":{"description":"Invalid or missing date.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Bearer credential required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Credential lacks intelligence:read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Authentication or distributed limiting is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_intelligence"}},"/api/v1/intelligence/search":{"get":{"summary":"Run alias-expanded lexical search over public content","description":"Requires intelligence:read. This is deterministic lexical search, not semantic/vector search.","security":[{"AgentBearer":[]}],"parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":500}},{"name":"topic","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"explain","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Ranked public results with optional field-level evidence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelligenceSearch"}}}},"400":{"description":"Invalid query, date, or limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Bearer credential required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Credential lacks intelligence:read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Authentication or distributed limiting is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_intelligence_search"}},"/api/events":{"post":{"summary":"Record one privacy-minimal first-party aggregate event","description":"Same-origin only. Search text, referrer URLs, visitor identifiers, and arbitrary dimensions are rejected.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsEvent"}}}},"responses":{"204":{"description":"Event recorded."},"400":{"description":"Malformed event or unknown target."},"403":{"description":"The request is not same-origin."},"429":{"description":"The shared request limit was exceeded."},"503":{"description":"Distributed aggregate storage is unavailable."}},"operationId":"post_api_events"}},"/api/v1/agent/drafts":{"post":{"summary":"Create an isolated agent-authored editorial proposal","description":"Requires draft:create. The server forces draft state and protected publication fields.","security":[{"AgentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDraftContent"}}}},"responses":{"201":{"description":"Draft proposal created."},"400":{"description":"Invalid content or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Bearer credential required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Credential lacks draft:create.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Slug or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Request exceeds 256 KB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Authentication, Redis, or audit signing is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"post_api_v1_agent_drafts"}},"/api/v1/agent/drafts/{draftId}":{"get":{"summary":"Read one proposal and its chained audit events","security":[{"AgentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/DraftId"}],"responses":{"200":{"description":"Stored proposal and audit chain."},"401":{"description":"Bearer credential required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Credential lacks draft:read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Draft not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_agent_drafts_draftId","description":"Read one proposal and its chained audit events"},"put":{"summary":"Replace editable proposal content","description":"Requires draft:update and an exact expectedRevision. Frozen proposals cannot be changed.","security":[{"AgentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/DraftId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["expectedRevision","content"],"properties":{"expectedRevision":{"type":"integer","minimum":1},"content":{"$ref":"#/components/schemas/AgentDraftContent"}}}}}},"responses":{"200":{"description":"Proposal revised."},"409":{"description":"Revision conflict, frozen proposal, or integrity failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"put_api_v1_agent_drafts_draftId"}},"/api/v1/agent/drafts/{draftId}/sources":{"post":{"summary":"Attach an attributable source to a proposal","security":[{"AgentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/DraftId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["expectedRevision","source"],"properties":{"expectedRevision":{"type":"integer","minimum":1},"source":{"$ref":"#/components/schemas/Source"}}}}}},"responses":{"200":{"description":"Source attached."},"409":{"description":"Revision, duplicate source, frozen proposal, or integrity conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"post_api_v1_agent_drafts_draftId_sources","description":"Attach an attributable source to a proposal"}},"/api/v1/agent/drafts/{draftId}/validate":{"get":{"summary":"Validate proposal readiness and stored integrity","security":[{"AgentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/DraftId"}],"responses":{"200":{"description":"Deterministic quality, content hash, provenance, and audit-chain results."}},"operationId":"get_api_v1_agent_drafts_draftId_validate","description":"Validate proposal readiness and stored integrity"}},"/api/v1/agent/drafts/{draftId}/preview":{"get":{"summary":"Preview canonical proposal content","security":[{"AgentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/DraftId"}],"responses":{"200":{"description":"Structured post, agent Markdown, and validation result."},"409":{"description":"Stored integrity verification failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"get_api_v1_agent_drafts_draftId_preview","description":"Preview canonical proposal content"}},"/api/v1/agent/drafts/{draftId}/review":{"post":{"summary":"Request human review and permanently freeze the proposal","security":[{"AgentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/DraftId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpectedRevision"}}}},"responses":{"200":{"description":"Review requested and proposal frozen."},"409":{"description":"Revision, state, or integrity conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Proposal has not passed deterministic validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"post_api_v1_agent_drafts_draftId_review","description":"Request human review and permanently freeze the proposal"}},"/api/v1/agent/drafts/{draftId}/pull-request":{"post":{"summary":"Create a dry-run result or constrained draft pull request","description":"Requires repo:pr after review request. No merge or publication operation exists.","security":[{"AgentBearer":[]}],"parameters":[{"$ref":"#/components/parameters/DraftId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpectedRevision"}}}},"responses":{"200":{"description":"Dry-run coordinates or draft pull request created."},"409":{"description":"Revision, state, repository, or integrity conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Repository adapter is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"post_api_v1_agent_drafts_draftId_pull_request"}}},"components":{"securitySchemes":{"AgentBearer":{"type":"http","scheme":"bearer","bearerFormat":"opaque"}},"parameters":{"DraftId":{"name":"draftId","in":"path","required":true,"schema":{"type":"string","pattern":"^draft_[a-f0-9]{32}$"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}},"schemas":{"ApiError":{"type":"object","required":["error"],"additionalProperties":true,"properties":{"error":{"type":"string"},"code":{"type":"string"}}},"Source":{"type":"object","additionalProperties":false,"required":["title","url","publisher"],"properties":{"title":{"type":"string","minLength":3,"maxLength":300},"url":{"type":"string","format":"uri","pattern":"^https://"},"publisher":{"type":"string","minLength":2,"maxLength":160},"publishedAt":{"type":"string","format":"date"}}},"ExpectedRevision":{"type":"object","additionalProperties":false,"required":["expectedRevision"],"properties":{"expectedRevision":{"type":"integer","minimum":1}}},"AgentDraftContent":{"type":"object","additionalProperties":false,"required":["title","slug","summary","directAnswer","topic","tags","image","imageAlt","seoTitle","seoDescription","targetQuestion","keyTakeaways","sources","imageCredit","imageLicense","body"],"properties":{"title":{"type":"string","minLength":20,"maxLength":100},"slug":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"summary":{"type":"string","minLength":40,"maxLength":220},"directAnswer":{"type":"string","minLength":40,"maxLength":420},"topic":{"type":"string","minLength":2},"tags":{"type":"array","minItems":1,"items":{"type":"string"}},"image":{"type":"string"},"imageAlt":{"type":"string","minLength":12,"maxLength":180},"seoTitle":{"type":"string","minLength":20,"maxLength":70},"seoDescription":{"type":"string","minLength":50,"maxLength":180},"targetQuestion":{"type":"string","minLength":10},"keyTakeaways":{"type":"array","minItems":2,"maxItems":6,"items":{"type":"string","minLength":10}},"sources":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/Source"}},"definitions":{"type":"array","items":{"type":"object"}},"statistics":{"type":"array","items":{"type":"object"}},"expertQuotes":{"type":"array","items":{"type":"object"}},"comparisonTables":{"type":"array","items":{"type":"object"}},"faqs":{"type":"array","items":{"type":"object"}},"ctas":{"type":"array","items":{"type":"object"}},"imageCredit":{"type":"string","minLength":2,"maxLength":180},"imageLicense":{"type":"string","minLength":2,"maxLength":120},"imageSourceUrl":{"type":"string","format":"uri","pattern":"^https://"},"body":{"type":"string","minLength":300,"maxLength":120000}}},"ContentSummary":{"type":"object","required":["id","slug","title","summary","url","publishedAt","updatedAt","qualityScore"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"directAnswer":{"type":"string"},"body":{"type":"string"},"topic":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"publishedAt":{"type":"string","format":"date"},"updatedAt":{"type":"string","format":"date"},"qualityScore":{"type":"integer","minimum":0,"maximum":100},"quality":{"$ref":"#/components/schemas/QualityReport"},"url":{"type":"string","format":"uri"}}},"QualityReport":{"type":"object","required":["score","threshold","ready","checks","recommendations"],"properties":{"score":{"type":"integer","minimum":0,"maximum":100},"threshold":{"type":"integer","minimum":0,"maximum":100},"ready":{"type":"boolean"},"checks":{"type":"array","items":{"type":"object","required":["id","label","status","points","maxPoints","evidence"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"status":{"type":"string","enum":["pass","warn","fail"]},"points":{"type":"integer"},"maxPoints":{"type":"integer"},"evidence":{"type":"string"}}}},"recommendations":{"type":"array","items":{"type":"string"}}}},"ContentResults":{"type":"object","required":["total","count","page","pageCount","limit","posts"],"properties":{"total":{"type":"integer"},"count":{"type":"integer"},"page":{"type":"integer"},"pageCount":{"type":"integer"},"limit":{"type":"integer"},"posts":{"type":"array","items":{"$ref":"#/components/schemas/ContentSummary"}}}},"ContentDocument":{"allOf":[{"$ref":"#/components/schemas/ContentSummary"},{"type":"object","required":["body","quality","representations","sources"],"properties":{"body":{"type":"string"},"quality":{"$ref":"#/components/schemas/QualityReport"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"representations":{"type":"object","required":["html","markdown","json"],"properties":{"html":{"type":"string","format":"uri"},"markdown":{"type":"string","format":"uri"},"json":{"type":"string","format":"uri"}}}}}]},"PublicProvenance":{"type":"object","additionalProperties":false,"required":["version","sourcePath","canonicalMarkdownHash","contentHash","schemaVersion"],"properties":{"version":{"const":"sfa.provenance.v1"},"sourcePath":{"type":"string"},"canonicalMarkdownHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"contentHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"schemaVersion":{"type":"string"},"commit":{"type":"string"}}},"SourceBundle":{"type":"object","required":["version","content","provenance","methodology","limitations"],"properties":{"version":{"const":"sfa.source-bundle.v1"},"content":{"type":"object","required":["id","kind","language","url","updatedAt"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["post","translation","research-page","dataset"]},"language":{"type":"string"},"url":{"type":"string","format":"uri"},"updatedAt":{"type":"string","format":"date"}}},"provenance":{"$ref":"#/components/schemas/PublicProvenance"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"methodology":{"type":"array","items":{"type":"string","format":"uri"}},"limitations":{"type":"array","items":{"type":"string"}}}},"AdvancedContentSummary":{"type":"object","required":["id","kind","language","slug","title","summary","topic","tags","publishedAt","updatedAt","url","sourceBundleUrl"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["research-page","dataset"]},"language":{"const":"en"},"slug":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"topic":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"publishedAt":{"type":"string","format":"date"},"updatedAt":{"type":"string","format":"date"},"author":{"type":"string"},"reviewer":{"type":"string"},"url":{"type":"string","format":"uri"},"sourceBundleUrl":{"type":"string","format":"uri"},"license":{"type":"string"},"version":{"type":"string"}}},"AdvancedContentDocument":{"allOf":[{"$ref":"#/components/schemas/AdvancedContentSummary"},{"type":"object","required":["body","sources","methodologyRefs","provenance","representations"],"properties":{"body":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"methodologyRefs":{"type":"array","items":{"type":"string"}},"provenance":{"$ref":"#/components/schemas/PublicProvenance"},"representations":{"type":"object","required":["html","markdown","json"]}}}]},"ChangeFeed":{"type":"object","additionalProperties":false,"required":["version","cursor","nextCursor","count","events"],"properties":{"version":{"const":"sfa.changes.v1"},"cursor":{"type":["string","null"]},"nextCursor":{"type":["string","null"]},"count":{"type":"integer","minimum":0,"maximum":100},"events":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["eventId","cursor","type","occurredAt","content","contentHash","sourceBundleUrl"],"properties":{"eventId":{"type":"string"},"cursor":{"type":"string"},"type":{"type":"string","enum":["published","updated","translated","dataset-published","research-published"]},"occurredAt":{"type":"string","format":"date"},"content":{"type":"object","required":["id","kind","topic","language","url"]},"contentHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"sourceBundleUrl":{"type":"string","format":"uri"}}}}}},"CreateTopicSubscription":{"type":"object","additionalProperties":false,"required":["topics","eventTypes","endpoint","signingSecret"],"properties":{"topics":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string"}},"eventTypes":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","enum":["published","updated","translated","dataset-published","research-published"]}},"endpoint":{"type":"string","format":"uri","pattern":"^https://"},"signingSecret":{"type":"string","minLength":32,"maxLength":512,"writeOnly":true}}},"TopicSubscription":{"type":"object","additionalProperties":false,"required":["id","topics","eventTypes","endpoint","createdBy","createdAt"],"properties":{"id":{"type":"string","pattern":"^sub_[a-f0-9]{32}$"},"topics":{"type":"array","items":{"type":"string"}},"eventTypes":{"type":"array","items":{"type":"string"}},"endpoint":{"type":"string","format":"uri"},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"IntelligenceReport":{"type":"object","additionalProperties":false,"required":["version","asOf","corpus","graph","recommendations"],"properties":{"version":{"const":"sfa.intelligence.v1"},"asOf":{"type":"string","format":"date"},"corpus":{"type":"object","additionalProperties":false,"required":["posts","topics","tags","sources","entities"],"properties":{"posts":{"type":"integer","minimum":0,"maximum":500},"topics":{"type":"integer","minimum":0},"tags":{"type":"integer","minimum":0},"sources":{"type":"integer","minimum":0,"maximum":50000},"entities":{"type":"integer","minimum":0}}},"graph":{"type":"object","additionalProperties":false,"required":["nodes","edges"],"properties":{"nodes":{"type":"array","items":{"$ref":"#/components/schemas/IntelligenceGraphNode"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/IntelligenceGraphEdge"}}}},"recommendations":{"type":"object","additionalProperties":false,"required":["duplicates","gaps","freshness","citations","internalLinks","entities","relatedQuestions"],"properties":{"duplicates":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/DuplicateRecommendation"}},"gaps":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/GapRecommendation"}},"freshness":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/FreshnessRecommendation"}},"citations":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/CitationRecommendation"}},"internalLinks":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/InternalLinkRecommendation"}},"entities":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/EntityRecommendation"}},"relatedQuestions":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/RelatedQuestionSet"}}}}}},"IntelligenceSearch":{"type":"object","additionalProperties":false,"required":["query","total","results"],"properties":{"query":{"type":"object","additionalProperties":false,"required":["raw","normalized","terms","expanded"],"properties":{"raw":{"type":"string"},"normalized":{"type":"string"},"terms":{"type":"array","items":{"type":"string"}},"expanded":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["input","canonical","reason"],"properties":{"input":{"type":"string"},"canonical":{"type":"string"},"reason":{"const":"alias"}}}}}},"total":{"type":"integer","minimum":0},"results":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/IntelligenceSearchResult"}}}},"IntelligenceGraphNode":{"type":"object","additionalProperties":false,"required":["id","kind","label"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["post","topic","tag","source","entity","author"]},"label":{"type":"string"},"metadata":{"type":"object","additionalProperties":true}}},"IntelligenceGraphEdge":{"type":"object","additionalProperties":false,"required":["id","from","to","relation","weight","evidence"],"properties":{"id":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"relation":{"type":"string","enum":["has_topic","has_tag","authored_by","cites","mentions","links_to","similar_to"]},"weight":{"type":"number","minimum":0},"evidence":{"type":"array","items":{"type":"string"}}}},"IntelligenceSearchResult":{"type":"object","additionalProperties":false,"required":["slug","title","topic","tags","publishedAt","updatedAt","score"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"topic":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"publishedAt":{"type":"string","format":"date"},"updatedAt":{"type":"string","format":"date"},"score":{"type":"number","minimum":0},"matches":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["field","term","occurrences","weight"],"properties":{"field":{"type":"string","enum":["title","targetQuestion","topic","summary","directAnswer","body","tags"]},"term":{"type":"string"},"occurrences":{"type":"integer","minimum":1},"weight":{"type":"number","minimum":0}}}}}},"DuplicateRecommendation":{"type":"object","additionalProperties":false,"required":["id","leftSlug","rightSlug","score","signals","evidence"],"properties":{"id":{"type":"string"},"leftSlug":{"type":"string"},"rightSlug":{"type":"string"},"score":{"type":"number","minimum":0,"maximum":1},"signals":{"type":"array","items":{"type":"string","enum":["same-normalized-title","same-target-question","high-token-overlap","shared-topic","shared-tags"]}},"evidence":{"type":"object","additionalProperties":false,"required":["sharedTags","sameTopic"],"properties":{"sharedTags":{"type":"array","items":{"type":"string"}},"sameTopic":{"type":"boolean"}}}}},"GapRecommendation":{"type":"object","additionalProperties":false,"required":["id","targetId","title","query","reason","bestMatches","suggestedAction"],"properties":{"id":{"type":"string"},"targetId":{"type":"string"},"title":{"type":"string"},"query":{"type":"string"},"reason":{"type":"string","enum":["no-match","weak-match","missing-required-taxonomy"]},"bestMatches":{"type":"array","maxItems":3,"items":{"type":"object","additionalProperties":false,"required":["slug","score"],"properties":{"slug":{"type":"string"},"score":{"type":"number","minimum":0}}}},"suggestedAction":{"type":"string","enum":["create-content","revise-existing-content"]}}},"FreshnessRecommendation":{"type":"object","additionalProperties":false,"required":["id","slug","ageDays","thresholdDays","signals","suggestedAction","evidence"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"ageDays":{"type":"integer","minimum":0},"thresholdDays":{"type":"integer","minimum":1},"signals":{"type":"array","items":{"type":"string","enum":["updated-age","old-source"]}},"suggestedAction":{"const":"refresh"},"evidence":{"type":"object","additionalProperties":false,"required":["updatedAt","oldSources"],"properties":{"updatedAt":{"type":"string","format":"date"},"oldSources":{"type":"array","items":{"type":"string","format":"uri"}}}}}},"CitationRecommendation":{"type":"object","additionalProperties":false,"required":["id","slug","code","field","suggestedAction","evidence"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"code":{"type":"string","enum":["missing-source-date","duplicate-source","low-source-depth","claim-needs-citation","structured-quote-without-source"]},"field":{"type":"string"},"suggestedAction":{"type":"string","enum":["add-source-date","dedupe-source","add-source"]},"evidence":{"type":"object","additionalProperties":true}}},"InternalLinkRecommendation":{"type":"object","additionalProperties":false,"required":["id","fromSlug","toSlug","score","anchorText","reasons","evidence"],"properties":{"id":{"type":"string"},"fromSlug":{"type":"string"},"toSlug":{"type":"string"},"score":{"type":"number","minimum":0},"anchorText":{"type":"string"},"reasons":{"type":"array","items":{"type":"string","enum":["shared-topic","shared-tag","lexical-overlap"]}},"evidence":{"type":"object","additionalProperties":false,"required":["sharedTags","lexical"],"properties":{"sharedTags":{"type":"array","items":{"type":"string"}},"lexical":{"type":"number","minimum":0,"maximum":1}}}}},"EntityRecommendation":{"type":"object","additionalProperties":false,"required":["id","slug","entityId","code","suggestedAction","evidence"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"entityId":{"type":"string"},"code":{"type":"string","enum":["missing-expected-tag","missing-expected-topic","canonical-label-variant"]},"suggestedAction":{"type":"string","enum":["add-tag","review-topic","normalize-label"]},"evidence":{"type":"object","additionalProperties":true}}},"RelatedQuestionSet":{"type":"object","additionalProperties":false,"required":["slug","questions"],"properties":{"slug":{"type":"string"},"questions":{"type":"array","items":{"type":"string"}}}},"AnalyticsEvent":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","path"],"properties":{"type":{"const":"page_view"},"path":{"type":"string"}}},{"type":"object","additionalProperties":false,"required":["type","content"],"properties":{"type":{"const":"reading_complete"},"content":{"type":"string"}}},{"type":"object","additionalProperties":false,"required":["type","category"],"properties":{"type":{"enum":["search","zero_results"]},"category":{"enum":["web-search","industry-search","life-sciences","search-infrastructure","other"]}}},{"type":"object","additionalProperties":false,"required":["type","content","cta"],"properties":{"type":{"const":"cta_click"},"content":{"type":"string"},"cta":{"type":"integer","minimum":0,"maximum":20}}},{"type":"object","additionalProperties":false,"required":["type","path","source"],"properties":{"type":{"const":"ai_referral"},"path":{"type":"string"},"source":{"enum":["chatgpt","perplexity","claude","gemini","copilot","other-ai"]}}}]}}},"externalDocs":{"url":"https://www.searchforagents.com/llms.txt"}}