{"openapi":"3.1.0","info":{"title":"Cortex API","version":"1.0.0","description":"API for the Cortex intelligence engine. Only routes migrated to the contract layer are documented here."},"servers":[{"url":""}],"tags":[{"name":"Projects","description":"Create, list, inspect, update, and change the status of projects. You can also manage which sources are attached to a project.\n\nA project is the top-level organizational container within Cortex that groups related feeds and sources under a shared objective."},{"name":"Sources","description":"Create, list, inspect, update, and change the status of sources, or trigger ingestion for a specific source.\n\nA source is an external content provider that Cortex connects to for periodically retrieving raw content."},{"name":"Feeds","description":"Create, list, inspect, update, and change the status of feeds. You can also manage which sources are attached to a feed.\n\nA feed is a configured ingestion channel governed by an objective that determines which incoming content items are relevant and how they are summarized."},{"name":"Digests","description":"Create, list, inspect, update, and change the status of digests. You can also trigger digest executions and inspect their outputs.\n\nA digest is a configured, recurring output of Cortex that consumes content from one or more feeds and produces a structured deliverable aligned to its objective."},{"name":"Processing Events","description":"List and filter processing events for ingestion and digest execution history.\n\nA processing event is a persisted record of a workflow or task state transition within Cortex processing. It captures execution status, timestamps, and related context so operators can inspect what happened during ingestion or digest execution."},{"name":"Feedback","description":"Create, list, and retrieve feedback records. Submit quality feedback on digest outputs, feed items, or chat responses.\n\nFeedback is an evaluative signal recorded by a user or client about the quality, usefulness, or correctness of a Cortex decision, output, or response."},{"name":"Optimization","description":"Trigger optimization runs, inspect optimization history, and manage active patches and revisions."},{"name":"Workspace Reorganizations","description":"Plan and execute batch workspace restructuring operations. Supports moving feeds and digests between projects, linking and unlinking project sources, and evaluating impacts before committing changes. Uses a two-phase plan/apply workflow with stale-plan detection and idempotent apply."},{"name":"Content Items","description":"List and retrieve processed content items. Content items represent individual pieces of source material after ingestion processing.\n\nA content item is a piece of raw content that has been retrieved and extracted from a source."},{"name":"Source Catalog","description":"Browse the source catalog. Search for available source templates and inspect catalog entry details."},{"name":"Examples","description":"List and retrieve example project setups. Examples demonstrate real-world Cortex configurations with typed composition data and linked guide content."},{"name":"Documentation","description":"Search and retrieve normalized product documentation. The corpus includes source-type guides, digest-type guides, example guides, and API reference docs."},{"name":"Credentials","description":"Issue, list, and revoke API credentials.\n\nAn API credential is a managed authentication artifact issued by Cortex for programmatic access to the API. It belongs to an organization, is scoped by role and status, and is presented exactly once as a secret at creation time."}],"paths":{"/api/sources":{"get":{"operationId":"listSources","summary":"List sources with optional filters","tags":["Sources"],"description":"Returns a paginated list of sources for the authenticated organization. Supports filtering by status, source type, health, and pagination via limit/offset.","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","paused","archived"]}},{"name":"type","in":"query","required":false,"schema":{"description":"Filter sources by one or more source types. Use a comma-separated list such as \"rss,web\".","type":"string"},"description":"Filter sources by one or more source types. Use a comma-separated list such as \"rss,web\"."},{"name":"health","in":"query","required":false,"schema":{"description":"Filter sources by one or more health values. Use a comma-separated list such as \"healthy,error\".","type":"string"},"description":"Filter sources by one or more health values. Use a comma-separated list such as \"healthy,error\"."},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"description":"Maximum number of results to return. Default: 50.","type":"integer"},"description":"Maximum number of results to return. Default: 50."},{"name":"offset","in":"query","required":false,"schema":{"minimum":0,"description":"Number of results to skip for pagination. Default: 0.","type":"integer"},"description":"Number of results to skip for pagination. Default: 0."},{"name":"projectIds","in":"query","required":false,"schema":{"description":"Comma-separated list of project IDs to scope sources via active feed links.","type":"string"},"description":"Comma-separated list of project IDs to scope sources via active feed links."}],"responses":{"200":{"description":"Paginated list of sources","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","org_id","name","type","status","visibility","current_version","created_by_user_id","created_at","feed_link_mode","cursor_state","pause_provenance","failure_streak_count","failure_streak_started_at","source_versions","version","health","last_event_at","content_item_count","schedule_status"],"properties":{"id":{"type":"string"},"org_id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["rss","web","x_profile","x_list","x_search","api_endpoint"]},"status":{"type":"string","enum":["active","paused","archived"]},"visibility":{"type":"string","enum":["private","org_shared"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feed_link_mode":{"type":"string","enum":["all","explicit"]},"cursor_state":{"anyOf":[{},{"type":"null"}]},"pause_provenance":{"anyOf":[{"const":"manual","type":"string"},{"const":"auto_unhealthy","type":"string"},{"type":"null"}]},"failure_streak_count":{"type":"integer"},"failure_streak_started_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"source_versions":{"type":"array","items":{"type":"object","required":["id","source_id","version","connector_config","change_reason","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"source_id":{"type":"string"},"version":{"type":"integer"},"connector_config":{},"change_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"version":{"anyOf":[{"type":"object","required":["id","source_id","version","connector_config","change_reason","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"source_id":{"type":"string"},"version":{"type":"integer"},"connector_config":{},"change_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"content_item_count":{"type":"integer"},"schedule_status":{"anyOf":[{"const":"pending","type":"string"},{"const":"synced","type":"string"},{"const":"failed","type":"string"},{"type":"null"}]}}}},"meta":{"type":"object","required":["requestId","total","limit","offset"],"properties":{"requestId":{"format":"uuid","type":"string"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"post":{"operationId":"createSource","summary":"Create a new source","tags":["Sources"],"description":"Creates a new content source for the authenticated organization. Requires admin role. Supports RSS, web, X (profile/list/search), and API endpoint source types. Each type has specific connector configuration requirements.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"additionalProperties":false,"title":"RSS source","type":"object","required":["name","sourceType","url"],"properties":{"name":{"minLength":1,"description":"Human-readable display name for the source.","type":"string"},"cron":{"description":"Schedule in standard 5-field cron format: minute hour day-of-month month day-of-week. Example: \"0 0 * * *\" runs daily at midnight UTC. Omit this field to use the default schedule for the source type.","examples":["0 0 * * *","0 */4 * * *"],"type":"string"},"feedIds":{"description":"Explicit list of feed IDs to link this source to. Only used when feedLinkMode is \"explicit\". Ignored when feedLinkMode is \"all\".","type":"array","items":{"type":"string"}},"feedLinkMode":{"description":"Controls automatic feed linking. \"all\" links this source to every active feed in the org. \"explicit\" links only to feeds specified in feedIds. Default: explicit.","type":"string","enum":["all","explicit"]},"projectIds":{"description":"Project IDs the source should be linked to via project_sources. Required for Builder-scoped creation so the source is visible in the originating project even when no feeds are linked yet. Each id must belong to the caller's org.","type":"array","items":{"minLength":1,"type":"string"}},"status":{"description":"Initial status of the source. \"active\" enables immediate scheduling; \"paused\" creates the source without scheduling. Default: paused.","type":"string","enum":["active","paused"]},"id":{"description":"Client-supplied ID. If omitted, a UUID is generated server-side.","type":"string"},"ingestionLimits":{"additionalProperties":false,"description":"Per-source ingestion limits. Overrides the platform defaults. Values are clamped by platform upper bounds when configured.","type":"object","properties":{"max_items_per_extraction":{"minimum":0,"description":"Max items to extract per poll. 0 = no source cap (uses platform upper bound if set). Blank = inherit platform default.","type":"integer"},"content_max_age_days":{"minimum":0,"description":"Skip content older than N days. 0 = no source age cutoff (uses platform upper bound if set). Blank = inherit platform default.","type":"integer"}}},"sourceType":{"const":"rss","type":"string"},"url":{"minLength":1,"description":"URL of the RSS or Atom feed.","examples":["https://example.com/rss","https://blog.example.com/feed.xml"],"type":"string"},"connectorConfig":{"description":"Optional additional connector settings. Typically not needed for RSS sources.","type":"object","patternProperties":{"^(.*)$":{}}}}},{"additionalProperties":false,"title":"Web source","type":"object","required":["name","sourceType","url","connectorConfig"],"properties":{"name":{"minLength":1,"description":"Human-readable display name for the source.","type":"string"},"cron":{"description":"Schedule in standard 5-field cron format: minute hour day-of-month month day-of-week. Example: \"0 0 * * *\" runs daily at midnight UTC. Omit this field to use the default schedule for the source type.","examples":["0 0 * * *","0 */4 * * *"],"type":"string"},"feedIds":{"description":"Explicit list of feed IDs to link this source to. Only used when feedLinkMode is \"explicit\". Ignored when feedLinkMode is \"all\".","type":"array","items":{"type":"string"}},"feedLinkMode":{"description":"Controls automatic feed linking. \"all\" links this source to every active feed in the org. \"explicit\" links only to feeds specified in feedIds. Default: explicit.","type":"string","enum":["all","explicit"]},"projectIds":{"description":"Project IDs the source should be linked to via project_sources. Required for Builder-scoped creation so the source is visible in the originating project even when no feeds are linked yet. Each id must belong to the caller's org.","type":"array","items":{"minLength":1,"type":"string"}},"status":{"description":"Initial status of the source. \"active\" enables immediate scheduling; \"paused\" creates the source without scheduling. Default: paused.","type":"string","enum":["active","paused"]},"id":{"description":"Client-supplied ID. If omitted, a UUID is generated server-side.","type":"string"},"ingestionLimits":{"additionalProperties":false,"description":"Per-source ingestion limits. Overrides the platform defaults. Values are clamped by platform upper bounds when configured.","type":"object","properties":{"max_items_per_extraction":{"minimum":0,"description":"Max items to extract per poll. 0 = no source cap (uses platform upper bound if set). Blank = inherit platform default.","type":"integer"},"content_max_age_days":{"minimum":0,"description":"Skip content older than N days. 0 = no source age cutoff (uses platform upper bound if set). Blank = inherit platform default.","type":"integer"}}},"sourceType":{"const":"web","type":"string"},"url":{"minLength":1,"description":"URL of the listing page to scrape. The page is loaded in a headless browser and items are extracted using the configured selectors.","examples":["https://example.com/blog","https://news.example.com/"],"type":"string"},"connectorConfig":{"description":"Web scraping configuration. \"selectors\" extracts items from the listing page. \"pageSelectors\" optionally extracts metadata from each linked article page. \"linkTransform\" optionally rewrites extracted URLs.","type":"object","required":["selectors"],"properties":{"selectors":{"description":"CSS selectors for extracting items from the listing page. item and link are required; title, date, and dateAttribute are optional listing-level metadata selectors.","type":"object","required":["item","link"],"properties":{"item":{"minLength":1,"description":"CSS selector for the repeating container element on the listing page. Each match becomes one content item.","examples":["article.blog-card","div.post-entry","li.feed-item"],"type":"string"},"link":{"minLength":1,"description":"CSS selector for the link element within each item container. Use \":self\" if the item element itself is an <a> tag.","examples":["a","a.post-link",":self"],"type":"string"},"title":{"minLength":1,"description":"CSS selector for the title element within each listing item. Extracts the title from the listing page rather than the linked article.","examples":["h3","h2.post-title"],"type":"string"},"date":{"minLength":1,"description":"CSS selector for the date element within each listing item.","examples":["time","span.date","h3 + div"],"type":"string"},"dateAttribute":{"minLength":1,"description":"HTML attribute on the listing-level date element that contains the date value. Omit to read the element text content.","examples":["datetime","content"],"type":"string"}}},"pageSelectors":{"description":"Optional selectors applied to each linked article page to extract structured metadata. If omitted, only listing-page data is used.","type":"object","properties":{"title":{"minLength":1,"description":"CSS selector for the article title on the linked article page.","examples":["h1","h1.article-title"],"type":"string"},"date":{"minLength":1,"description":"CSS selector for the publish-date element on the linked article page.","examples":["time","span.date"],"type":"string"},"dateAttribute":{"minLength":1,"description":"HTML attribute on the date element that contains the date value. Omit to read the element text content.","examples":["datetime"],"type":"string"}}},"linkTransform":{"description":"Optional regex transform applied to extracted URLs before they become canonical URLs. Useful for converting view-URLs to raw/API URLs.","type":"object","required":["match","replace"],"properties":{"match":{"minLength":1,"description":"Regex pattern applied to each resolved listing URL before canonicalization.","examples":["github\\.com/([^/]+)/([^/]+)/blob/([^/]+)/(.*)"],"type":"string"},"replace":{"minLength":1,"description":"Regex replacement string for rewritten listing URLs.","examples":["raw.githubusercontent.com/$1/$2/refs/heads/$3/$4"],"type":"string"}}},"waitFor":{"minLength":1,"description":"Wait condition before extraction. Prefix with \"css:\" for a CSS selector wait, or use a raw expression.","examples":["css:a[href*='/blog/']"],"type":"string"},"jsCode":{"minLength":1,"description":"JavaScript code to execute in the page context before extraction.","type":"string"},"delaySeconds":{"minimum":0,"description":"Additional delay in seconds after page load before extraction.","type":"number"},"userAgent":{"minLength":1,"description":"Custom User-Agent header for page requests.","type":"string"}}}}},{"additionalProperties":false,"title":"X profile source","type":"object","required":["name","sourceType","connectorConfig"],"properties":{"name":{"minLength":1,"description":"Human-readable display name for the source.","type":"string"},"cron":{"description":"Schedule in standard 5-field cron format: minute hour day-of-month month day-of-week. Example: \"0 0 * * *\" runs daily at midnight UTC. Omit this field to use the default schedule for the source type.","examples":["0 0 * * *","0 */4 * * *"],"type":"string"},"feedIds":{"description":"Explicit list of feed IDs to link this source to. Only used when feedLinkMode is \"explicit\". Ignored when feedLinkMode is \"all\".","type":"array","items":{"type":"string"}},"feedLinkMode":{"description":"Controls automatic feed linking. \"all\" links this source to every active feed in the org. \"explicit\" links only to feeds specified in feedIds. Default: explicit.","type":"string","enum":["all","explicit"]},"projectIds":{"description":"Project IDs the source should be linked to via project_sources. Required for Builder-scoped creation so the source is visible in the originating project even when no feeds are linked yet. Each id must belong to the caller's org.","type":"array","items":{"minLength":1,"type":"string"}},"status":{"description":"Initial status of the source. \"active\" enables immediate scheduling; \"paused\" creates the source without scheduling. Default: paused.","type":"string","enum":["active","paused"]},"id":{"description":"Client-supplied ID. If omitted, a UUID is generated server-side.","type":"string"},"ingestionLimits":{"additionalProperties":false,"description":"Per-source ingestion limits. Overrides the platform defaults. Values are clamped by platform upper bounds when configured.","type":"object","properties":{"max_items_per_extraction":{"minimum":0,"description":"Max items to extract per poll. 0 = no source cap (uses platform upper bound if set). Blank = inherit platform default.","type":"integer"},"content_max_age_days":{"minimum":0,"description":"Skip content older than N days. 0 = no source age cutoff (uses platform upper bound if set). Blank = inherit platform default.","type":"integer"}}},"sourceType":{"const":"x_profile","type":"string"},"connectorConfig":{"description":"X profile polling configuration. Fetches recent tweets from the specified user.","type":"object","required":["username"],"properties":{"username":{"pattern":"^@?[a-zA-Z0-9_]{1,15}$","description":"X (Twitter) username to monitor. Leading @ is optional.","examples":["solana","@ethereum"],"type":"string"},"max_results":{"minimum":1,"maximum":200,"description":"Maximum tweets to fetch per poll cycle. Default: 200.","type":"integer"},"min_likes":{"minimum":0,"description":"Skip tweets with fewer likes than this threshold. Default: 0 (no filter).","type":"integer"},"min_retweets":{"minimum":0,"description":"Skip tweets with fewer retweets than this threshold. Default: 0 (no filter).","type":"integer"},"min_replies":{"minimum":0,"description":"Skip tweets with fewer replies than this threshold. Default: 0 (no filter).","type":"integer"},"exclude_retweets":{"description":"Exclude retweets from the results. Default: false.","type":"boolean"},"exclude_replies":{"description":"Exclude replies from the results. Default: false.","type":"boolean"}}}}},{"additionalProperties":false,"title":"X list source","type":"object","required":["name","sourceType","connectorConfig"],"properties":{"name":{"minLength":1,"description":"Human-readable display name for the source.","type":"string"},"cron":{"description":"Schedule in standard 5-field cron format: minute hour day-of-month month day-of-week. Example: \"0 0 * * *\" runs daily at midnight UTC. Omit this field to use the default schedule for the source type.","examples":["0 0 * * *","0 */4 * * *"],"type":"string"},"feedIds":{"description":"Explicit list of feed IDs to link this source to. Only used when feedLinkMode is \"explicit\". Ignored when feedLinkMode is \"all\".","type":"array","items":{"type":"string"}},"feedLinkMode":{"description":"Controls automatic feed linking. \"all\" links this source to every active feed in the org. \"explicit\" links only to feeds specified in feedIds. Default: explicit.","type":"string","enum":["all","explicit"]},"projectIds":{"description":"Project IDs the source should be linked to via project_sources. Required for Builder-scoped creation so the source is visible in the originating project even when no feeds are linked yet. Each id must belong to the caller's org.","type":"array","items":{"minLength":1,"type":"string"}},"status":{"description":"Initial status of the source. \"active\" enables immediate scheduling; \"paused\" creates the source without scheduling. Default: paused.","type":"string","enum":["active","paused"]},"id":{"description":"Client-supplied ID. If omitted, a UUID is generated server-side.","type":"string"},"ingestionLimits":{"additionalProperties":false,"description":"Per-source ingestion limits. Overrides the platform defaults. Values are clamped by platform upper bounds when configured.","type":"object","properties":{"max_items_per_extraction":{"minimum":0,"description":"Max items to extract per poll. 0 = no source cap (uses platform upper bound if set). Blank = inherit platform default.","type":"integer"},"content_max_age_days":{"minimum":0,"description":"Skip content older than N days. 0 = no source age cutoff (uses platform upper bound if set). Blank = inherit platform default.","type":"integer"}}},"sourceType":{"const":"x_list","type":"string"},"connectorConfig":{"description":"X list polling configuration. Fetches recent tweets from the specified list.","type":"object","required":["list_id"],"properties":{"list_id":{"description":"X list identifier. Accepts either a numeric list ID or a full X list URL. The URL form is normalized to a numeric ID before storage.","examples":["1234567890","https://x.com/i/lists/1234567890"],"type":"string"},"max_results":{"minimum":1,"maximum":200,"description":"Maximum tweets to fetch per poll cycle. Default: 200.","type":"integer"},"min_likes":{"minimum":0,"description":"Skip tweets with fewer likes than this threshold. Default: 0 (no filter).","type":"integer"},"min_retweets":{"minimum":0,"description":"Skip tweets with fewer retweets than this threshold. Default: 0 (no filter).","type":"integer"},"min_replies":{"minimum":0,"description":"Skip tweets with fewer replies than this threshold. Default: 0 (no filter).","type":"integer"},"exclude_retweets":{"description":"Exclude retweets from the results. Default: false.","type":"boolean"},"exclude_replies":{"description":"Exclude replies from the results. Default: false.","type":"boolean"}}}}},{"additionalProperties":false,"title":"X search source","type":"object","required":["name","sourceType","connectorConfig"],"properties":{"name":{"minLength":1,"description":"Human-readable display name for the source.","type":"string"},"cron":{"description":"Schedule in standard 5-field cron format: minute hour day-of-month month day-of-week. Example: \"0 0 * * *\" runs daily at midnight UTC. Omit this field to use the default schedule for the source type.","examples":["0 0 * * *","0 */4 * * *"],"type":"string"},"feedIds":{"description":"Explicit list of feed IDs to link this source to. Only used when feedLinkMode is \"explicit\". Ignored when feedLinkMode is \"all\".","type":"array","items":{"type":"string"}},"feedLinkMode":{"description":"Controls automatic feed linking. \"all\" links this source to every active feed in the org. \"explicit\" links only to feeds specified in feedIds. Default: explicit.","type":"string","enum":["all","explicit"]},"projectIds":{"description":"Project IDs the source should be linked to via project_sources. Required for Builder-scoped creation so the source is visible in the originating project even when no feeds are linked yet. Each id must belong to the caller's org.","type":"array","items":{"minLength":1,"type":"string"}},"status":{"description":"Initial status of the source. \"active\" enables immediate scheduling; \"paused\" creates the source without scheduling. Default: paused.","type":"string","enum":["active","paused"]},"id":{"description":"Client-supplied ID. If omitted, a UUID is generated server-side.","type":"string"},"ingestionLimits":{"additionalProperties":false,"description":"Per-source ingestion limits. Overrides the platform defaults. Values are clamped by platform upper bounds when configured.","type":"object","properties":{"max_items_per_extraction":{"minimum":0,"description":"Max items to extract per poll. 0 = no source cap (uses platform upper bound if set). Blank = inherit platform default.","type":"integer"},"content_max_age_days":{"minimum":0,"description":"Skip content older than N days. 0 = no source age cutoff (uses platform upper bound if set). Blank = inherit platform default.","type":"integer"}}},"sourceType":{"const":"x_search","type":"string"},"connectorConfig":{"description":"X search polling configuration. Runs the query periodically and ingests matching tweets.","type":"object","required":["query"],"properties":{"query":{"minLength":1,"maxLength":512,"description":"X search query passed directly to the Search API. Supports standard operators: has:links, is:verified, -is:retweet, lang:en, OR, AND, quotes for exact match.","examples":["(crypto OR bitcoin OR defi) is:verified -is:retweet lang:en","solana has:links -is:retweet"],"type":"string"},"sort_order":{"default":"relevancy","description":"Search result ordering. \"relevancy\" (default): fresh ranked search each poll, no cursor. \"recency\": newest-first with incremental cursor-based polling.","type":"string","enum":["relevancy","recency"]},"max_results":{"minimum":1,"maximum":200,"description":"Maximum tweets to fetch per poll cycle. Default: 200.","type":"integer"},"min_likes":{"minimum":0,"description":"Skip tweets with fewer likes than this threshold. Default: 0 (no filter).","type":"integer"},"min_retweets":{"minimum":0,"description":"Skip tweets with fewer retweets than this threshold. Default: 0 (no filter).","type":"integer"},"min_replies":{"minimum":0,"description":"Skip tweets with fewer replies than this threshold. Default: 0 (no filter).","type":"integer"},"exclude_retweets":{"description":"Exclude retweets from the results. Default: false.","type":"boolean"},"exclude_replies":{"description":"Exclude replies from the results. Default: false.","type":"boolean"}}}}},{"additionalProperties":false,"title":"API endpoint source","type":"object","required":["name","sourceType","connectorConfig"],"properties":{"name":{"minLength":1,"description":"Human-readable display name for the source.","type":"string"},"cron":{"description":"Schedule in standard 5-field cron format: minute hour day-of-month month day-of-week. Example: \"0 0 * * *\" runs daily at midnight UTC. Omit this field to use the default schedule for the source type.","examples":["0 0 * * *","0 */4 * * *"],"type":"string"},"feedIds":{"description":"Explicit list of feed IDs to link this source to. Only used when feedLinkMode is \"explicit\". Ignored when feedLinkMode is \"all\".","type":"array","items":{"type":"string"}},"feedLinkMode":{"description":"Controls automatic feed linking. \"all\" links this source to every active feed in the org. \"explicit\" links only to feeds specified in feedIds. Default: explicit.","type":"string","enum":["all","explicit"]},"projectIds":{"description":"Project IDs the source should be linked to via project_sources. Required for Builder-scoped creation so the source is visible in the originating project even when no feeds are linked yet. Each id must belong to the caller's org.","type":"array","items":{"minLength":1,"type":"string"}},"status":{"description":"Initial status of the source. \"active\" enables immediate scheduling; \"paused\" creates the source without scheduling. Default: paused.","type":"string","enum":["active","paused"]},"id":{"description":"Client-supplied ID. If omitted, a UUID is generated server-side.","type":"string"},"ingestionLimits":{"additionalProperties":false,"description":"Per-source ingestion limits. Overrides the platform defaults. Values are clamped by platform upper bounds when configured.","type":"object","properties":{"max_items_per_extraction":{"minimum":0,"description":"Max items to extract per poll. 0 = no source cap (uses platform upper bound if set). Blank = inherit platform default.","type":"integer"},"content_max_age_days":{"minimum":0,"description":"Skip content older than N days. 0 = no source age cutoff (uses platform upper bound if set). Blank = inherit platform default.","type":"integer"}}},"sourceType":{"const":"api_endpoint","type":"string"},"url":{"minLength":1,"description":"URL of the JSON API endpoint (legacy). Prefer connectorConfig.request.url.","type":"string"},"connectorConfig":{"anyOf":[{"additionalProperties":false,"type":"object","required":["request","extract"],"properties":{"request":{"additionalProperties":false,"type":"object","required":["url"],"properties":{"url":{"minLength":1,"description":"HTTPS URL of the JSON API endpoint.","type":"string"},"auth":{"additionalProperties":false,"type":"object","required":["mode","credentialRef"],"properties":{"mode":{"const":"bearer_credential","type":"string"},"credentialRef":{"minLength":1,"maxLength":128,"type":"string"}}},"headers":{"maxItems":5,"type":"array","items":{"additionalProperties":false,"type":"object","required":["name","value"],"properties":{"name":{"minLength":1,"maxLength":64,"type":"string"},"value":{"minLength":1,"maxLength":256,"type":"string"}}}}}},"extract":{"additionalProperties":false,"type":"object","required":["itemsPath","urlPath","textPath"],"properties":{"itemsPath":{"minLength":1,"description":"JSONPath expression selecting the array of items in the API response.","examples":["$.items[*]","$.data.articles[*]","$[*]"],"type":"string"},"urlPath":{"minLength":1,"description":"JSONPath expression selecting each item's canonical URL (relative to each item).","examples":["$.url","$.link","$.canonical_url"],"type":"string"},"textPath":{"minLength":1,"description":"JSONPath expression selecting each item's main text content (relative to each item).","examples":["$.body","$.content","$.description"],"type":"string"},"titlePath":{"minLength":1,"description":"JSONPath expression selecting each item's title (relative to each item). Optional.","examples":["$.title","$.headline"],"type":"string"},"publishedAtPath":{"minLength":1,"description":"JSONPath expression selecting each item's publish timestamp (relative to each item). Optional; parsed as ISO 8601.","examples":["$.published_at","$.date","$.created"],"type":"string"}}}}},{"additionalProperties":false,"type":"object","required":["itemsPath","urlPath","textPath"],"properties":{"itemsPath":{"minLength":1,"type":"string"},"urlPath":{"minLength":1,"type":"string"},"textPath":{"minLength":1,"type":"string"},"titlePath":{"minLength":1,"type":"string"},"publishedAtPath":{"minLength":1,"type":"string"}}}]}}}],"discriminator":{"propertyName":"sourceType"}}}}},"responses":{"201":{"description":"Newly created source","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","org_id","name","type","status","visibility","current_version","created_by_user_id","created_at","feed_link_mode","cursor_state","pause_provenance","failure_streak_count","failure_streak_started_at","source_versions","feed_sources","version","health","last_event_at","schedule_status"],"properties":{"id":{"type":"string"},"org_id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["rss","web","x_profile","x_list","x_search","api_endpoint"]},"status":{"type":"string","enum":["active","paused","archived"]},"visibility":{"type":"string","enum":["private","org_shared"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feed_link_mode":{"type":"string","enum":["all","explicit"]},"cursor_state":{"anyOf":[{},{"type":"null"}]},"pause_provenance":{"anyOf":[{"const":"manual","type":"string"},{"const":"auto_unhealthy","type":"string"},{"type":"null"}]},"failure_streak_count":{"type":"integer"},"failure_streak_started_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"source_versions":{"type":"array","items":{"type":"object","required":["id","source_id","version","connector_config","change_reason","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"source_id":{"type":"string"},"version":{"type":"integer"},"connector_config":{},"change_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"feed_sources":{"type":"array","items":{"type":"object","required":["feed_id","source_id","status","created_at","feeds"],"properties":{"feed_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feeds":{"type":"object","required":["id","name","status"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}}}}}},"version":{"anyOf":[{"type":"object","required":["id","source_id","version","connector_config","change_reason","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"source_id":{"type":"string"},"version":{"type":"integer"},"connector_config":{},"change_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule_status":{"anyOf":[{"const":"pending","type":"string"},{"const":"synced","type":"string"},{"const":"failed","type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/sources/{id}":{"get":{"operationId":"getSource","summary":"Get source details","tags":["Sources"],"description":"Returns full source details including current version, health status, and schedule status for the specified source.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Source ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Source ID"}],"responses":{"200":{"description":"Source details including version and health","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","org_id","name","type","status","visibility","current_version","created_by_user_id","created_at","feed_link_mode","cursor_state","pause_provenance","failure_streak_count","failure_streak_started_at","source_versions","feed_sources","version","health","last_event_at","schedule_status"],"properties":{"id":{"type":"string"},"org_id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["rss","web","x_profile","x_list","x_search","api_endpoint"]},"status":{"type":"string","enum":["active","paused","archived"]},"visibility":{"type":"string","enum":["private","org_shared"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feed_link_mode":{"type":"string","enum":["all","explicit"]},"cursor_state":{"anyOf":[{},{"type":"null"}]},"pause_provenance":{"anyOf":[{"const":"manual","type":"string"},{"const":"auto_unhealthy","type":"string"},{"type":"null"}]},"failure_streak_count":{"type":"integer"},"failure_streak_started_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"source_versions":{"type":"array","items":{"type":"object","required":["id","source_id","version","connector_config","change_reason","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"source_id":{"type":"string"},"version":{"type":"integer"},"connector_config":{},"change_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"feed_sources":{"type":"array","items":{"type":"object","required":["feed_id","source_id","status","created_at","feeds"],"properties":{"feed_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feeds":{"type":"object","required":["id","name","status"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}}}}}},"version":{"anyOf":[{"type":"object","required":["id","source_id","version","connector_config","change_reason","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"source_id":{"type":"string"},"version":{"type":"integer"},"connector_config":{},"change_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule_status":{"anyOf":[{"const":"pending","type":"string"},{"const":"synced","type":"string"},{"const":"failed","type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Source not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"patch":{"operationId":"updateSource","summary":"Update source configuration","tags":["Sources"],"description":"Updates source properties. Body shape depends on the source type (resolved from the database). At least one field must be provided. Requires admin role.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Source ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Source ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"additionalProperties":false,"title":"RSS source update","type":"object","properties":{"name":{"minLength":1,"description":"Updated display name.","type":"string"},"cron":{"description":"Set a custom 5-field cron schedule, or null to revert to the source-type default schedule.","anyOf":[{"description":"Schedule in standard 5-field cron format: minute hour day-of-month month day-of-week. Example: \"0 0 * * *\" runs daily at midnight UTC. Omit this field to use the default schedule for the source type.","examples":["0 0 * * *","0 */4 * * *"],"type":"string"},{"description":"Clear the custom schedule and revert to the default schedule for this source type.","type":"null"}]},"feedIds":{"description":"Updated list of feed IDs to link to. Only applies when feedLinkMode is \"explicit\".","type":"array","items":{"type":"string"}},"feedLinkMode":{"type":"string","enum":["all","explicit"]},"changeReason":{"description":"Human-readable reason for the change. Stored in the version audit trail.","type":"string"},"ingestionLimits":{"additionalProperties":false,"description":"Per-source ingestion limits for updates. Send null to clear a saved override and inherit the platform default again.","type":"object","properties":{"max_items_per_extraction":{"anyOf":[{"minimum":0,"description":"Max items to extract per poll. 0 = no source cap (uses platform upper bound if set).","type":"integer"},{"description":"Clears the per-source override so the source inherits the platform default.","type":"null"}]},"content_max_age_days":{"anyOf":[{"minimum":0,"description":"Skip content older than N days. 0 = no source age cutoff (uses platform upper bound if set).","type":"integer"},{"description":"Clears the per-source override so the source inherits the platform default.","type":"null"}]}}},"url":{"minLength":1,"type":"string"}}},{"additionalProperties":false,"title":"Web source update","type":"object","properties":{"name":{"minLength":1,"description":"Updated display name.","type":"string"},"cron":{"description":"Set a custom 5-field cron schedule, or null to revert to the source-type default schedule.","anyOf":[{"description":"Schedule in standard 5-field cron format: minute hour day-of-month month day-of-week. Example: \"0 0 * * *\" runs daily at midnight UTC. Omit this field to use the default schedule for the source type.","examples":["0 0 * * *","0 */4 * * *"],"type":"string"},{"description":"Clear the custom schedule and revert to the default schedule for this source type.","type":"null"}]},"feedIds":{"description":"Updated list of feed IDs to link to. Only applies when feedLinkMode is \"explicit\".","type":"array","items":{"type":"string"}},"feedLinkMode":{"type":"string","enum":["all","explicit"]},"changeReason":{"description":"Human-readable reason for the change. Stored in the version audit trail.","type":"string"},"ingestionLimits":{"additionalProperties":false,"description":"Per-source ingestion limits for updates. Send null to clear a saved override and inherit the platform default again.","type":"object","properties":{"max_items_per_extraction":{"anyOf":[{"minimum":0,"description":"Max items to extract per poll. 0 = no source cap (uses platform upper bound if set).","type":"integer"},{"description":"Clears the per-source override so the source inherits the platform default.","type":"null"}]},"content_max_age_days":{"anyOf":[{"minimum":0,"description":"Skip content older than N days. 0 = no source age cutoff (uses platform upper bound if set).","type":"integer"},{"description":"Clears the per-source override so the source inherits the platform default.","type":"null"}]}}},"url":{"minLength":1,"type":"string"},"connectorConfig":{"type":"object","required":["selectors"],"properties":{"selectors":{"description":"CSS selectors for extracting items from the listing page. item and link are required; title, date, and dateAttribute are optional listing-level metadata selectors.","type":"object","required":["item","link"],"properties":{"item":{"minLength":1,"description":"CSS selector for the repeating container element on the listing page. Each match becomes one content item.","examples":["article.blog-card","div.post-entry","li.feed-item"],"type":"string"},"link":{"minLength":1,"description":"CSS selector for the link element within each item container. Use \":self\" if the item element itself is an <a> tag.","examples":["a","a.post-link",":self"],"type":"string"},"title":{"minLength":1,"description":"CSS selector for the title element within each listing item. Extracts the title from the listing page rather than the linked article.","examples":["h3","h2.post-title"],"type":"string"},"date":{"minLength":1,"description":"CSS selector for the date element within each listing item.","examples":["time","span.date","h3 + div"],"type":"string"},"dateAttribute":{"minLength":1,"description":"HTML attribute on the listing-level date element that contains the date value. Omit to read the element text content.","examples":["datetime","content"],"type":"string"}}},"pageSelectors":{"description":"Optional selectors applied to each linked article page to extract structured metadata. If omitted, only listing-page data is used.","type":"object","properties":{"title":{"minLength":1,"description":"CSS selector for the article title on the linked article page.","examples":["h1","h1.article-title"],"type":"string"},"date":{"minLength":1,"description":"CSS selector for the publish-date element on the linked article page.","examples":["time","span.date"],"type":"string"},"dateAttribute":{"minLength":1,"description":"HTML attribute on the date element that contains the date value. Omit to read the element text content.","examples":["datetime"],"type":"string"}}},"linkTransform":{"description":"Optional regex transform applied to extracted URLs before they become canonical URLs. Useful for converting view-URLs to raw/API URLs.","type":"object","required":["match","replace"],"properties":{"match":{"minLength":1,"description":"Regex pattern applied to each resolved listing URL before canonicalization.","examples":["github\\.com/([^/]+)/([^/]+)/blob/([^/]+)/(.*)"],"type":"string"},"replace":{"minLength":1,"description":"Regex replacement string for rewritten listing URLs.","examples":["raw.githubusercontent.com/$1/$2/refs/heads/$3/$4"],"type":"string"}}},"waitFor":{"anyOf":[{"minLength":1,"type":"string"},{"type":"null"}]},"jsCode":{"anyOf":[{"minLength":1,"type":"string"},{"type":"null"}]},"delaySeconds":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}]},"userAgent":{"anyOf":[{"minLength":1,"type":"string"},{"type":"null"}]}}}}},{"additionalProperties":false,"title":"X profile source update","type":"object","properties":{"name":{"minLength":1,"description":"Updated display name.","type":"string"},"cron":{"description":"Set a custom 5-field cron schedule, or null to revert to the source-type default schedule.","anyOf":[{"description":"Schedule in standard 5-field cron format: minute hour day-of-month month day-of-week. Example: \"0 0 * * *\" runs daily at midnight UTC. Omit this field to use the default schedule for the source type.","examples":["0 0 * * *","0 */4 * * *"],"type":"string"},{"description":"Clear the custom schedule and revert to the default schedule for this source type.","type":"null"}]},"feedIds":{"description":"Updated list of feed IDs to link to. Only applies when feedLinkMode is \"explicit\".","type":"array","items":{"type":"string"}},"feedLinkMode":{"type":"string","enum":["all","explicit"]},"changeReason":{"description":"Human-readable reason for the change. Stored in the version audit trail.","type":"string"},"ingestionLimits":{"additionalProperties":false,"description":"Per-source ingestion limits for updates. Send null to clear a saved override and inherit the platform default again.","type":"object","properties":{"max_items_per_extraction":{"anyOf":[{"minimum":0,"description":"Max items to extract per poll. 0 = no source cap (uses platform upper bound if set).","type":"integer"},{"description":"Clears the per-source override so the source inherits the platform default.","type":"null"}]},"content_max_age_days":{"anyOf":[{"minimum":0,"description":"Skip content older than N days. 0 = no source age cutoff (uses platform upper bound if set).","type":"integer"},{"description":"Clears the per-source override so the source inherits the platform default.","type":"null"}]}}},"connectorConfig":{"type":"object","properties":{"username":{"pattern":"^@?[a-zA-Z0-9_]{1,15}$","type":"string"},"max_results":{"anyOf":[{"minimum":1,"maximum":200,"description":"Maximum tweets to fetch per poll cycle. Default: 200.","type":"integer"},{"description":"Clears the saved max-results override so the source uses the default again.","type":"null"}]},"min_likes":{"anyOf":[{"minimum":0,"description":"Skip tweets with fewer likes than this threshold. Default: 0 (no filter).","type":"integer"},{"description":"Clears the saved minimum likes threshold so the source uses the default again.","type":"null"}]},"min_retweets":{"anyOf":[{"minimum":0,"description":"Skip tweets with fewer retweets than this threshold. Default: 0 (no filter).","type":"integer"},{"description":"Clears the saved minimum retweets threshold so the source uses the default again.","type":"null"}]},"min_replies":{"anyOf":[{"minimum":0,"description":"Skip tweets with fewer replies than this threshold. Default: 0 (no filter).","type":"integer"},{"description":"Clears the saved minimum replies threshold so the source uses the default again.","type":"null"}]},"exclude_retweets":{"anyOf":[{"description":"Exclude retweets from the results.","type":"boolean"},{"description":"Clears the saved exclude-retweets override.","type":"null"}]},"exclude_replies":{"anyOf":[{"description":"Exclude replies from the results.","type":"boolean"},{"description":"Clears the saved exclude-replies override.","type":"null"}]}}}}},{"additionalProperties":false,"title":"X list source update","type":"object","properties":{"name":{"minLength":1,"description":"Updated display name.","type":"string"},"cron":{"description":"Set a custom 5-field cron schedule, or null to revert to the source-type default schedule.","anyOf":[{"description":"Schedule in standard 5-field cron format: minute hour day-of-month month day-of-week. Example: \"0 0 * * *\" runs daily at midnight UTC. Omit this field to use the default schedule for the source type.","examples":["0 0 * * *","0 */4 * * *"],"type":"string"},{"description":"Clear the custom schedule and revert to the default schedule for this source type.","type":"null"}]},"feedIds":{"description":"Updated list of feed IDs to link to. Only applies when feedLinkMode is \"explicit\".","type":"array","items":{"type":"string"}},"feedLinkMode":{"type":"string","enum":["all","explicit"]},"changeReason":{"description":"Human-readable reason for the change. Stored in the version audit trail.","type":"string"},"ingestionLimits":{"additionalProperties":false,"description":"Per-source ingestion limits for updates. Send null to clear a saved override and inherit the platform default again.","type":"object","properties":{"max_items_per_extraction":{"anyOf":[{"minimum":0,"description":"Max items to extract per poll. 0 = no source cap (uses platform upper bound if set).","type":"integer"},{"description":"Clears the per-source override so the source inherits the platform default.","type":"null"}]},"content_max_age_days":{"anyOf":[{"minimum":0,"description":"Skip content older than N days. 0 = no source age cutoff (uses platform upper bound if set).","type":"integer"},{"description":"Clears the per-source override so the source inherits the platform default.","type":"null"}]}}},"connectorConfig":{"type":"object","properties":{"list_id":{"type":"string"},"max_results":{"anyOf":[{"minimum":1,"maximum":200,"description":"Maximum tweets to fetch per poll cycle. Default: 200.","type":"integer"},{"description":"Clears the saved max-results override so the source uses the default again.","type":"null"}]},"min_likes":{"anyOf":[{"minimum":0,"description":"Skip tweets with fewer likes than this threshold. Default: 0 (no filter).","type":"integer"},{"description":"Clears the saved minimum likes threshold so the source uses the default again.","type":"null"}]},"min_retweets":{"anyOf":[{"minimum":0,"description":"Skip tweets with fewer retweets than this threshold. Default: 0 (no filter).","type":"integer"},{"description":"Clears the saved minimum retweets threshold so the source uses the default again.","type":"null"}]},"min_replies":{"anyOf":[{"minimum":0,"description":"Skip tweets with fewer replies than this threshold. Default: 0 (no filter).","type":"integer"},{"description":"Clears the saved minimum replies threshold so the source uses the default again.","type":"null"}]},"exclude_retweets":{"anyOf":[{"description":"Exclude retweets from the results.","type":"boolean"},{"description":"Clears the saved exclude-retweets override.","type":"null"}]},"exclude_replies":{"anyOf":[{"description":"Exclude replies from the results.","type":"boolean"},{"description":"Clears the saved exclude-replies override.","type":"null"}]}}}}},{"additionalProperties":false,"title":"X search source update","type":"object","properties":{"name":{"minLength":1,"description":"Updated display name.","type":"string"},"cron":{"description":"Set a custom 5-field cron schedule, or null to revert to the source-type default schedule.","anyOf":[{"description":"Schedule in standard 5-field cron format: minute hour day-of-month month day-of-week. Example: \"0 0 * * *\" runs daily at midnight UTC. Omit this field to use the default schedule for the source type.","examples":["0 0 * * *","0 */4 * * *"],"type":"string"},{"description":"Clear the custom schedule and revert to the default schedule for this source type.","type":"null"}]},"feedIds":{"description":"Updated list of feed IDs to link to. Only applies when feedLinkMode is \"explicit\".","type":"array","items":{"type":"string"}},"feedLinkMode":{"type":"string","enum":["all","explicit"]},"changeReason":{"description":"Human-readable reason for the change. Stored in the version audit trail.","type":"string"},"ingestionLimits":{"additionalProperties":false,"description":"Per-source ingestion limits for updates. Send null to clear a saved override and inherit the platform default again.","type":"object","properties":{"max_items_per_extraction":{"anyOf":[{"minimum":0,"description":"Max items to extract per poll. 0 = no source cap (uses platform upper bound if set).","type":"integer"},{"description":"Clears the per-source override so the source inherits the platform default.","type":"null"}]},"content_max_age_days":{"anyOf":[{"minimum":0,"description":"Skip content older than N days. 0 = no source age cutoff (uses platform upper bound if set).","type":"integer"},{"description":"Clears the per-source override so the source inherits the platform default.","type":"null"}]}}},"connectorConfig":{"type":"object","properties":{"query":{"minLength":1,"maxLength":512,"type":"string"},"sort_order":{"default":"relevancy","description":"Search result ordering. \"relevancy\" (default): fresh ranked search each poll, no cursor. \"recency\": newest-first with incremental cursor-based polling.","type":"string","enum":["relevancy","recency"]},"max_results":{"anyOf":[{"minimum":1,"maximum":200,"description":"Maximum tweets to fetch per poll cycle. Default: 200.","type":"integer"},{"description":"Clears the saved max-results override so the source uses the default again.","type":"null"}]},"min_likes":{"anyOf":[{"minimum":0,"description":"Skip tweets with fewer likes than this threshold. Default: 0 (no filter).","type":"integer"},{"description":"Clears the saved minimum likes threshold so the source uses the default again.","type":"null"}]},"min_retweets":{"anyOf":[{"minimum":0,"description":"Skip tweets with fewer retweets than this threshold. Default: 0 (no filter).","type":"integer"},{"description":"Clears the saved minimum retweets threshold so the source uses the default again.","type":"null"}]},"min_replies":{"anyOf":[{"minimum":0,"description":"Skip tweets with fewer replies than this threshold. Default: 0 (no filter).","type":"integer"},{"description":"Clears the saved minimum replies threshold so the source uses the default again.","type":"null"}]},"exclude_retweets":{"anyOf":[{"description":"Exclude retweets from the results.","type":"boolean"},{"description":"Clears the saved exclude-retweets override.","type":"null"}]},"exclude_replies":{"anyOf":[{"description":"Exclude replies from the results.","type":"boolean"},{"description":"Clears the saved exclude-replies override.","type":"null"}]}}}}},{"title":"API endpoint source update","type":"object","properties":{"name":{"minLength":1,"description":"Updated display name.","type":"string"},"cron":{"description":"Set a custom 5-field cron schedule, or null to revert to the source-type default schedule.","anyOf":[{"description":"Schedule in standard 5-field cron format: minute hour day-of-month month day-of-week. Example: \"0 0 * * *\" runs daily at midnight UTC. Omit this field to use the default schedule for the source type.","examples":["0 0 * * *","0 */4 * * *"],"type":"string"},{"description":"Clear the custom schedule and revert to the default schedule for this source type.","type":"null"}]},"feedIds":{"description":"Updated list of feed IDs to link to. Only applies when feedLinkMode is \"explicit\".","type":"array","items":{"type":"string"}},"feedLinkMode":{"type":"string","enum":["all","explicit"]},"changeReason":{"description":"Human-readable reason for the change. Stored in the version audit trail.","type":"string"},"ingestionLimits":{"additionalProperties":false,"description":"Per-source ingestion limits for updates. Send null to clear a saved override and inherit the platform default again.","type":"object","properties":{"max_items_per_extraction":{"anyOf":[{"minimum":0,"description":"Max items to extract per poll. 0 = no source cap (uses platform upper bound if set).","type":"integer"},{"description":"Clears the per-source override so the source inherits the platform default.","type":"null"}]},"content_max_age_days":{"anyOf":[{"minimum":0,"description":"Skip content older than N days. 0 = no source age cutoff (uses platform upper bound if set).","type":"integer"},{"description":"Clears the per-source override so the source inherits the platform default.","type":"null"}]}}},"url":{"minLength":1,"type":"string"},"connectorConfig":{"anyOf":[{"additionalProperties":false,"type":"object","required":["request","extract"],"properties":{"request":{"additionalProperties":false,"type":"object","required":["url"],"properties":{"url":{"minLength":1,"description":"HTTPS URL of the JSON API endpoint.","type":"string"},"auth":{"additionalProperties":false,"type":"object","required":["mode","credentialRef"],"properties":{"mode":{"const":"bearer_credential","type":"string"},"credentialRef":{"minLength":1,"maxLength":128,"type":"string"}}},"headers":{"maxItems":5,"type":"array","items":{"additionalProperties":false,"type":"object","required":["name","value"],"properties":{"name":{"minLength":1,"maxLength":64,"type":"string"},"value":{"minLength":1,"maxLength":256,"type":"string"}}}}}},"extract":{"additionalProperties":false,"type":"object","required":["itemsPath","urlPath","textPath"],"properties":{"itemsPath":{"minLength":1,"description":"JSONPath expression selecting the array of items in the API response.","examples":["$.items[*]","$.data.articles[*]","$[*]"],"type":"string"},"urlPath":{"minLength":1,"description":"JSONPath expression selecting each item's canonical URL (relative to each item).","examples":["$.url","$.link","$.canonical_url"],"type":"string"},"textPath":{"minLength":1,"description":"JSONPath expression selecting each item's main text content (relative to each item).","examples":["$.body","$.content","$.description"],"type":"string"},"titlePath":{"minLength":1,"description":"JSONPath expression selecting each item's title (relative to each item). Optional.","examples":["$.title","$.headline"],"type":"string"},"publishedAtPath":{"minLength":1,"description":"JSONPath expression selecting each item's publish timestamp (relative to each item). Optional; parsed as ISO 8601.","examples":["$.published_at","$.date","$.created"],"type":"string"}}}}},{"additionalProperties":false,"type":"object","properties":{"itemsPath":{"minLength":1,"type":"string"},"urlPath":{"minLength":1,"type":"string"},"textPath":{"minLength":1,"type":"string"},"titlePath":{"minLength":1,"type":"string"},"publishedAtPath":{"minLength":1,"type":"string"}}}]}}}]}}}},"responses":{"200":{"description":"Updated source","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","org_id","name","type","status","visibility","current_version","created_by_user_id","created_at","feed_link_mode","cursor_state","pause_provenance","failure_streak_count","failure_streak_started_at","source_versions","feed_sources","version","health","last_event_at","schedule_status"],"properties":{"id":{"type":"string"},"org_id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["rss","web","x_profile","x_list","x_search","api_endpoint"]},"status":{"type":"string","enum":["active","paused","archived"]},"visibility":{"type":"string","enum":["private","org_shared"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feed_link_mode":{"type":"string","enum":["all","explicit"]},"cursor_state":{"anyOf":[{},{"type":"null"}]},"pause_provenance":{"anyOf":[{"const":"manual","type":"string"},{"const":"auto_unhealthy","type":"string"},{"type":"null"}]},"failure_streak_count":{"type":"integer"},"failure_streak_started_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"source_versions":{"type":"array","items":{"type":"object","required":["id","source_id","version","connector_config","change_reason","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"source_id":{"type":"string"},"version":{"type":"integer"},"connector_config":{},"change_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"feed_sources":{"type":"array","items":{"type":"object","required":["feed_id","source_id","status","created_at","feeds"],"properties":{"feed_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feeds":{"type":"object","required":["id","name","status"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}}}}}},"version":{"anyOf":[{"type":"object","required":["id","source_id","version","connector_config","change_reason","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"source_id":{"type":"string"},"version":{"type":"integer"},"connector_config":{},"change_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule_status":{"anyOf":[{"const":"pending","type":"string"},{"const":"synced","type":"string"},{"const":"failed","type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid body or empty update","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Non-admin caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Source not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/sources/{id}/status":{"patch":{"operationId":"updateSourceStatus","summary":"Update source status","tags":["Sources"],"description":"Transitions the source to a new status. Valid transitions: active, paused, archived. Requires admin role.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Source ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Source ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["active","paused","archived"]}}}}}},"responses":{"200":{"description":"Updated source","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","org_id","name","type","status","visibility","current_version","created_by_user_id","created_at","feed_link_mode","cursor_state","pause_provenance","failure_streak_count","failure_streak_started_at","source_versions","feed_sources","version","health","last_event_at","schedule_status"],"properties":{"id":{"type":"string"},"org_id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["rss","web","x_profile","x_list","x_search","api_endpoint"]},"status":{"type":"string","enum":["active","paused","archived"]},"visibility":{"type":"string","enum":["private","org_shared"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feed_link_mode":{"type":"string","enum":["all","explicit"]},"cursor_state":{"anyOf":[{},{"type":"null"}]},"pause_provenance":{"anyOf":[{"const":"manual","type":"string"},{"const":"auto_unhealthy","type":"string"},{"type":"null"}]},"failure_streak_count":{"type":"integer"},"failure_streak_started_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"source_versions":{"type":"array","items":{"type":"object","required":["id","source_id","version","connector_config","change_reason","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"source_id":{"type":"string"},"version":{"type":"integer"},"connector_config":{},"change_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"feed_sources":{"type":"array","items":{"type":"object","required":["feed_id","source_id","status","created_at","feeds"],"properties":{"feed_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feeds":{"type":"object","required":["id","name","status"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}}}}}},"version":{"anyOf":[{"type":"object","required":["id","source_id","version","connector_config","change_reason","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"source_id":{"type":"string"},"version":{"type":"integer"},"connector_config":{},"change_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule_status":{"anyOf":[{"const":"pending","type":"string"},{"const":"synced","type":"string"},{"const":"failed","type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid status value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Source not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/sources/{id}/trigger":{"post":{"operationId":"triggerSourceIngestion","summary":"Trigger source ingestion","tags":["Sources"],"description":"Triggers an ingestion run for the specified source. The source must not be archived. Requires admin role.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Source ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Source ID"}],"responses":{"200":{"description":"Ingestion workflow triggered","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["workflow_id","source_id","trigger_type"],"properties":{"workflow_id":{"type":"string"},"source_id":{"type":"string"},"trigger_type":{"const":"manual","type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Source not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Source is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Manual ingestion ceiling reached for this org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/sources/{id}/test":{"post":{"operationId":"startSourceTest","summary":"Start a source test (dry-run validation)","tags":["Sources"],"description":"Starts a dry-run validation of the saved source configuration. Runs real fetch and extraction without persisting normal ingestion artifacts. Returns a correlation handle for polling the result. The source must not be archived. Requires admin role.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Source ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Source ID"}],"responses":{"202":{"description":"Test run started","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["test_run_id","source_id","source_type","source_config_version","status","started_at"],"properties":{"test_run_id":{"description":"Correlation handle for the test run","type":"string"},"source_id":{"type":"string"},"source_type":{"type":"string","enum":["rss","web","x_profile","x_list","x_search","api_endpoint"]},"source_config_version":{"type":"number"},"status":{"const":"running","type":"string"},"started_at":{"format":"date-time","type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Non-admin caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Source not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Source is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/sources/{id}/test/{testRunId}":{"get":{"operationId":"getSourceTestResult","summary":"Get source test result","tags":["Sources"],"description":"Returns the current status and result of a source test run. If the test is still running, status will be \"running\". Terminal states are \"pass\", \"warning\", or \"failed\" with validation metrics, structured warnings/failures, and bounded sample records.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Source ID","type":"string"},"description":"Source ID"},{"name":"testRunId","in":"path","required":true,"schema":{"description":"Test run correlation ID","type":"string"},"description":"Test run correlation ID"}],"responses":{"200":{"description":"Test result","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["test_run_id","source_id","source_type","source_config_version","status","started_at","completed_at","duration_ms","metrics","warnings","failures","samples","estimation_info"],"properties":{"test_run_id":{"description":"Correlation handle for the test run","type":"string"},"source_id":{"type":"string"},"source_type":{"type":"string","enum":["rss","web","x_profile","x_list","x_search","api_endpoint"]},"source_config_version":{"type":"number"},"status":{"type":"string","enum":["running","pass","warning","failed"]},"started_at":{"format":"date-time","type":"string"},"completed_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}]},"metrics":{"anyOf":[{"type":"object","required":["total_items","items_with_title","items_without_title","items_with_date","items_without_date","warning_count"],"properties":{"total_items":{"type":"number"},"items_with_title":{"type":"number"},"items_without_title":{"type":"number"},"items_with_date":{"type":"number"},"items_without_date":{"type":"number"},"warning_count":{"type":"number"}}},{"type":"null"}]},"warnings":{"type":"array","items":{"type":"object","required":["code","message"],"properties":{"code":{"description":"Stable validation reason code","type":"string"},"message":{"description":"Operator-readable explanation","type":"string"}}}},"failures":{"type":"array","items":{"type":"object","required":["code","message"],"properties":{"code":{"description":"Stable validation reason code","type":"string"},"message":{"description":"Operator-readable explanation","type":"string"}}}},"samples":{"type":"array","items":{"type":"object","required":["title","url","published_at","snippet"],"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"snippet":{"anyOf":[{"type":"string"},{"type":"null"}]}}}},"estimation_info":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Source or test run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/projects":{"post":{"operationId":"createProject","summary":"Create a new project","tags":["Projects"],"description":"Creates a new project for the authenticated organization. Requires admin role. A project groups sources and digests around a common objective.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["name","objective"],"properties":{"name":{"minLength":1,"description":"Human-readable name for the project.","type":"string"},"objective":{"minLength":1,"description":"High-level goal or purpose of the project. Guides digest generation and feed processing.","type":"string"},"id":{"description":"Client-supplied ID. If omitted, a UUID is generated server-side.","type":"string"},"config":{"description":"Optional key-value configuration. Reserved for future use.","type":"object","patternProperties":{"^(.*)$":{}}}}}}}},"responses":{"201":{"description":"Newly created project","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","org_id","name","status","current_version","created_by_user_id","created_at","project_versions","version"],"properties":{"id":{"type":"string"},"org_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"project_versions":{"type":"array","items":{"type":"object","required":["id","project_id","version","objective","config","effective_from","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"project_id":{"type":"string"},"version":{"type":"integer"},"objective":{"type":"string"},"config":{"anyOf":[{},{"type":"null"}]},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"version":{"anyOf":[{"type":"object","required":["id","project_id","version","objective","config","effective_from","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"project_id":{"type":"string"},"version":{"type":"integer"},"objective":{"type":"string"},"config":{"anyOf":[{},{"type":"null"}]},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"get":{"operationId":"listProjects","summary":"List projects with optional filters","tags":["Projects"],"description":"Returns a paginated list of projects for the authenticated organization. Supports filtering by status.","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"description":"Maximum number of results to return. Default: 50.","type":"integer"},"description":"Maximum number of results to return. Default: 50."},{"name":"offset","in":"query","required":false,"schema":{"minimum":0,"description":"Number of results to skip for pagination. Default: 0.","type":"integer"},"description":"Number of results to skip for pagination. Default: 0."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","paused","archived"]}}],"responses":{"200":{"description":"Paginated list of projects","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","org_id","name","status","current_version","created_by_user_id","created_at","project_versions","version","feed_count","digest_count","source_count"],"properties":{"id":{"type":"string"},"org_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"project_versions":{"type":"array","items":{"type":"object","required":["id","project_id","version","objective","config","effective_from","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"project_id":{"type":"string"},"version":{"type":"integer"},"objective":{"type":"string"},"config":{"anyOf":[{},{"type":"null"}]},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"version":{"anyOf":[{"type":"object","required":["id","project_id","version","objective","config","effective_from","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"project_id":{"type":"string"},"version":{"type":"integer"},"objective":{"type":"string"},"config":{"anyOf":[{},{"type":"null"}]},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"feed_count":{"type":"integer"},"digest_count":{"type":"integer"},"source_count":{"type":"integer"}}}},"meta":{"type":"object","required":["requestId","total","limit","offset"],"properties":{"requestId":{"format":"uuid","type":"string"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/projects/{id}":{"get":{"operationId":"getProject","summary":"Get project details","tags":["Projects"],"description":"Returns full project details including configuration for the specified project.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Project ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Project ID"}],"responses":{"200":{"description":"Project details","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","org_id","name","status","current_version","created_by_user_id","created_at","project_versions","version"],"properties":{"id":{"type":"string"},"org_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"project_versions":{"type":"array","items":{"type":"object","required":["id","project_id","version","objective","config","effective_from","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"project_id":{"type":"string"},"version":{"type":"integer"},"objective":{"type":"string"},"config":{"anyOf":[{},{"type":"null"}]},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"version":{"anyOf":[{"type":"object","required":["id","project_id","version","objective","config","effective_from","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"project_id":{"type":"string"},"version":{"type":"integer"},"objective":{"type":"string"},"config":{"anyOf":[{},{"type":"null"}]},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"patch":{"operationId":"updateProject","summary":"Update project configuration","tags":["Projects"],"description":"Updates project properties. At least one field must be provided. Requires admin role.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Project ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"minProperties":1,"type":"object","properties":{"name":{"minLength":1,"description":"Updated display name.","type":"string"},"objective":{"description":"Updated project objective.","type":"string"},"config":{"description":"Updated key-value configuration.","type":"object","patternProperties":{"^(.*)$":{}}},"changeReason":{"description":"Human-readable reason for the change. Stored in the version audit trail.","type":"string"}}}}}},"responses":{"200":{"description":"Updated project","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","org_id","name","status","current_version","created_by_user_id","created_at","project_versions","version"],"properties":{"id":{"type":"string"},"org_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"project_versions":{"type":"array","items":{"type":"object","required":["id","project_id","version","objective","config","effective_from","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"project_id":{"type":"string"},"version":{"type":"integer"},"objective":{"type":"string"},"config":{"anyOf":[{},{"type":"null"}]},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"version":{"anyOf":[{"type":"object","required":["id","project_id","version","objective","config","effective_from","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"project_id":{"type":"string"},"version":{"type":"integer"},"objective":{"type":"string"},"config":{"anyOf":[{},{"type":"null"}]},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid body or empty update","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Non-admin caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/projects/{id}/status":{"patch":{"operationId":"updateProjectStatus","summary":"Update project status","tags":["Projects"],"description":"Transitions the project to a new status. All transitions are currently allowed.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Project ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["active","paused","archived"]}}}}}},"responses":{"200":{"description":"Updated project","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","org_id","name","status","current_version","created_by_user_id","created_at","project_versions","version"],"properties":{"id":{"type":"string"},"org_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"project_versions":{"type":"array","items":{"type":"object","required":["id","project_id","version","objective","config","effective_from","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"project_id":{"type":"string"},"version":{"type":"integer"},"objective":{"type":"string"},"config":{"anyOf":[{},{"type":"null"}]},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"version":{"anyOf":[{"type":"object","required":["id","project_id","version","objective","config","effective_from","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"project_id":{"type":"string"},"version":{"type":"integer"},"objective":{"type":"string"},"config":{"anyOf":[{},{"type":"null"}]},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid status value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Non-admin caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/projects/{id}/sources":{"post":{"operationId":"attachProjectSource","summary":"Link a source to a project","tags":["Projects"],"description":"Attaches a source to the project. Requires admin role.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Project ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["sourceId"],"properties":{"sourceId":{"description":"ID of the source to attach to this project.","type":"string"}}}}}},"responses":{"201":{"description":"Source linked to project","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","project_id","source_id","status","created_at"],"properties":{"id":{"type":"string"},"project_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Non-admin caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Project or source not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/projects/{id}/sources/{sourceId}":{"delete":{"operationId":"detachProjectSource","summary":"Unlink a source from a project","tags":["Projects"],"description":"Removes the link between a source and a project. Requires admin role.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Project ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Project ID"},{"name":"sourceId","in":"path","required":true,"schema":{"description":"Source ID","examples":["660e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Source ID"}],"responses":{"200":{"description":"Source unlinked from project","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","project_id","source_id","status","created_at"],"properties":{"id":{"type":"string"},"project_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Non-admin caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Link not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/credentials":{"post":{"operationId":"createApiCredential","summary":"Issue a new API credential","tags":["Credentials"],"description":"Issues a new API credential for the authenticated organization. The full secret is returned only in this response and cannot be retrieved again. Requires Org Admin role.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["name","role"],"properties":{"name":{"minLength":1,"maxLength":255,"type":"string"},"role":{"type":"string","enum":["org:admin","org:member"]}}}}}},"responses":{"201":{"description":"Newly issued credential with secret","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","name","keyPrefix","role","status","createdAt","secret"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"role":{"type":"string"},"status":{"type":"string"},"createdAt":{"description":"ISO 8601 timestamp","type":"string"},"secret":{"description":"Full API key — shown only once","type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid name or role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Caller is not Org Admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"get":{"operationId":"listApiCredentials","summary":"List API credentials","tags":["Credentials"],"description":"Returns metadata for all API credentials in the authenticated organization. Secrets are never included. Requires Org Admin role.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Credential metadata list","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","name","keyPrefix","role","status","createdAt","revokedAt","lastUsedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"role":{"type":"string"},"status":{"type":"string","enum":["active","revoked"]},"createdAt":{"description":"ISO 8601 timestamp","type":"string"},"revokedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}}}},"meta":{"type":"object","required":["requestId","total"],"properties":{"requestId":{"format":"uuid","type":"string"},"total":{"type":"integer"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Caller is not Org Admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/credentials/{id}":{"delete":{"operationId":"revokeApiCredential","summary":"Revoke an API credential","tags":["Credentials"],"description":"Revokes an API credential immediately. Subsequent requests using it will receive 401. Idempotent — revoking an already-revoked credential returns its current state. Requires Org Admin role.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Credential ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Credential ID"}],"responses":{"200":{"description":"Revoked credential metadata","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","name","keyPrefix","role","status","createdAt","revokedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"role":{"type":"string"},"status":{"const":"revoked","type":"string"},"createdAt":{"description":"ISO 8601 timestamp","type":"string"},"revokedAt":{"description":"ISO 8601 timestamp","type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Caller is not Org Admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Credential not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/feeds":{"post":{"operationId":"createFeed","summary":"Create a new feed","tags":["Feeds"],"description":"Creates a new feed in the specified project. Requires admin role.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["projectId","name","objective"],"properties":{"projectId":{"description":"ID of the project this feed belongs to.","type":"string"},"name":{"minLength":1,"description":"Human-readable name for the feed.","type":"string"},"objective":{"minLength":1,"description":"Instructions for the AI pipeline describing what content to capture and how to process it.","type":"string"},"config":{"description":"Optional key-value configuration. Reserved for future use.","type":"object","patternProperties":{"^(.*)$":{}}},"sourceIds":{"description":"Source IDs to link to this feed on creation.","type":"array","items":{"type":"string"}},"sourceLinkMode":{"description":"How to link sources to this feed. \"all\" auto-links all project sources; \"explicit\" requires manual linking. Default: explicit.","type":"string","enum":["all","none","explicit"]},"id":{"description":"Client-supplied ID. If omitted, a UUID is generated server-side.","type":"string"}}}}}},"responses":{"201":{"description":"Newly created feed","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","project_id","name","status","source_link_mode","current_version","created_by_user_id","created_at","feed_versions","steps","feed_sources","auto_optimize_enabled","version","health","last_event_at"],"properties":{"id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","archived"]},"source_link_mode":{"type":"string","enum":["all","explicit"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feed_versions":{"type":"array","items":{"type":"object","required":["id","feed_id","version","objective","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"feed_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"steps":{"type":"array","items":{"type":"object","required":["id","feed_id","step_type","step_position","status","current_version","created_by_user_id","created_at","step_versions"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"step_type":{"type":"string"},"step_position":{"type":"integer"},"status":{"type":"string"},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"step_versions":{"type":"array","items":{"type":"object","required":["id","step_id","version","objective","config","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"step_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}}}}},"feed_sources":{"type":"array","items":{"type":"object","required":["id","feed_id","source_id","status","created_at","sources","feed_source_policies"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"sources":{"type":"object","required":["id","name","status","type"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"type":{"type":"string"},"_count":{}}},"feed_source_policies":{"type":"array","items":{"type":"object","required":["id","feed_id","source_id","status","current_version","created_by_user_id","created_at","feed_source_policy_versions"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feed_source_policy_versions":{"type":"array","items":{"type":"object","required":["id","policy_id","version","config","is_active","created_at"],"properties":{"id":{"type":"integer"},"policy_id":{"type":"string"},"version":{"type":"integer"},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}}}}}}}},"auto_optimize_enabled":{"type":"boolean"},"version":{"anyOf":[{"type":"object","required":["id","feed_id","version","objective","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"feed_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"get":{"operationId":"listFeeds","summary":"List feeds with optional filters","tags":["Feeds"],"description":"Returns a paginated list of feeds for the authenticated organization. Supports filtering by project and status.","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"description":"Maximum number of results to return. Default: 50.","type":"integer"},"description":"Maximum number of results to return. Default: 50."},{"name":"offset","in":"query","required":false,"schema":{"minimum":0,"description":"Number of results to skip for pagination. Default: 0.","type":"integer"},"description":"Number of results to skip for pagination. Default: 0."},{"name":"projectId","in":"query","required":false,"schema":{"description":"Filter feeds by project ID.","type":"string"},"description":"Filter feeds by project ID."},{"name":"projectIds","in":"query","required":false,"schema":{"description":"Filter feeds by a comma-separated set of project IDs.","type":"string"},"description":"Filter feeds by a comma-separated set of project IDs."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","paused","archived"]}},{"name":"health","in":"query","required":false,"schema":{"description":"Filter feeds by one or more health values. Use a comma-separated list such as \"healthy,error\".","type":"string"},"description":"Filter feeds by one or more health values. Use a comma-separated list such as \"healthy,error\"."}],"responses":{"200":{"description":"Paginated list of feeds","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","project_id","name","status","source_link_mode","current_version","created_by_user_id","created_at","feed_versions","steps","projects","version","health","last_event_at","project_name","source_count"],"properties":{"id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","archived"]},"source_link_mode":{"type":"string","enum":["all","explicit"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feed_versions":{"type":"array","items":{"type":"object","required":["id","feed_id","version","objective","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"feed_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"steps":{"type":"array","items":{"type":"object","required":["id","feed_id","step_type","step_position","status","current_version","created_by_user_id","created_at","step_versions"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"step_type":{"type":"string"},"step_position":{"type":"integer"},"status":{"type":"string"},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"step_versions":{"type":"array","items":{"type":"object","required":["id","step_id","version","objective","config","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"step_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}}}}},"projects":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}},"version":{"anyOf":[{"type":"object","required":["id","feed_id","version","objective","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"feed_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"project_name":{"type":"string"},"source_count":{"type":"integer"}}}},"meta":{"type":"object","required":["requestId","total","limit","offset"],"properties":{"requestId":{"format":"uuid","type":"string"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/feeds/{id}":{"get":{"operationId":"getFeed","summary":"Get feed details","tags":["Feeds"],"description":"Returns full feed details including steps, sources, and health status.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Feed ID"}],"responses":{"200":{"description":"Feed details","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","project_id","name","status","source_link_mode","current_version","created_by_user_id","created_at","feed_versions","steps","feed_sources","auto_optimize_enabled","version","health","last_event_at"],"properties":{"id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","archived"]},"source_link_mode":{"type":"string","enum":["all","explicit"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feed_versions":{"type":"array","items":{"type":"object","required":["id","feed_id","version","objective","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"feed_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"steps":{"type":"array","items":{"type":"object","required":["id","feed_id","step_type","step_position","status","current_version","created_by_user_id","created_at","step_versions"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"step_type":{"type":"string"},"step_position":{"type":"integer"},"status":{"type":"string"},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"step_versions":{"type":"array","items":{"type":"object","required":["id","step_id","version","objective","config","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"step_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}}}}},"feed_sources":{"type":"array","items":{"type":"object","required":["id","feed_id","source_id","status","created_at","sources","feed_source_policies"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"sources":{"type":"object","required":["id","name","status","type"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"type":{"type":"string"},"_count":{}}},"feed_source_policies":{"type":"array","items":{"type":"object","required":["id","feed_id","source_id","status","current_version","created_by_user_id","created_at","feed_source_policy_versions"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feed_source_policy_versions":{"type":"array","items":{"type":"object","required":["id","policy_id","version","config","is_active","created_at"],"properties":{"id":{"type":"integer"},"policy_id":{"type":"string"},"version":{"type":"integer"},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}}}}}}}},"auto_optimize_enabled":{"type":"boolean"},"version":{"anyOf":[{"type":"object","required":["id","feed_id","version","objective","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"feed_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Feed not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"patch":{"operationId":"updateFeed","summary":"Update feed configuration","tags":["Feeds"],"description":"Updates feed properties. At least one field must be provided. Config is opaque JSON passthrough. Requires admin role.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Feed ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"minProperties":1,"type":"object","properties":{"name":{"minLength":1,"description":"Updated display name.","type":"string"},"objective":{"description":"Updated processing objective.","type":"string"},"config":{"description":"Updated key-value configuration.","type":"object","patternProperties":{"^(.*)$":{}}},"sourceLinkMode":{"type":"string","enum":["all","explicit"]},"sourceIds":{"description":"Replace the full set of linked source IDs.","type":"array","items":{"type":"string"}},"changeReason":{"description":"Human-readable reason for the change. Stored in the version audit trail.","type":"string"},"autoOptimizeEnabled":{"description":"Toggle automatic optimization for this feed.","type":"boolean"}}}}}},"responses":{"200":{"description":"Updated feed","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","project_id","name","status","source_link_mode","current_version","created_by_user_id","created_at","feed_versions","steps","feed_sources","auto_optimize_enabled","version","health","last_event_at"],"properties":{"id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","archived"]},"source_link_mode":{"type":"string","enum":["all","explicit"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feed_versions":{"type":"array","items":{"type":"object","required":["id","feed_id","version","objective","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"feed_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"steps":{"type":"array","items":{"type":"object","required":["id","feed_id","step_type","step_position","status","current_version","created_by_user_id","created_at","step_versions"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"step_type":{"type":"string"},"step_position":{"type":"integer"},"status":{"type":"string"},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"step_versions":{"type":"array","items":{"type":"object","required":["id","step_id","version","objective","config","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"step_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}}}}},"feed_sources":{"type":"array","items":{"type":"object","required":["id","feed_id","source_id","status","created_at","sources","feed_source_policies"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"sources":{"type":"object","required":["id","name","status","type"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"type":{"type":"string"},"_count":{}}},"feed_source_policies":{"type":"array","items":{"type":"object","required":["id","feed_id","source_id","status","current_version","created_by_user_id","created_at","feed_source_policy_versions"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feed_source_policy_versions":{"type":"array","items":{"type":"object","required":["id","policy_id","version","config","is_active","created_at"],"properties":{"id":{"type":"integer"},"policy_id":{"type":"string"},"version":{"type":"integer"},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}}}}}}}},"auto_optimize_enabled":{"type":"boolean"},"version":{"anyOf":[{"type":"object","required":["id","feed_id","version","objective","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"feed_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid body or empty update","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Non-admin caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Feed not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/feeds/{id}/status":{"patch":{"operationId":"updateFeedStatus","summary":"Update feed status","tags":["Feeds"],"description":"Transitions the feed to a new status. All transitions are currently allowed.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Feed ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["active","paused","archived"]}}}}}},"responses":{"200":{"description":"Updated feed","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","project_id","name","status","source_link_mode","current_version","created_by_user_id","created_at","feed_versions","steps","feed_sources","auto_optimize_enabled","version","health","last_event_at"],"properties":{"id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","archived"]},"source_link_mode":{"type":"string","enum":["all","explicit"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feed_versions":{"type":"array","items":{"type":"object","required":["id","feed_id","version","objective","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"feed_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"steps":{"type":"array","items":{"type":"object","required":["id","feed_id","step_type","step_position","status","current_version","created_by_user_id","created_at","step_versions"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"step_type":{"type":"string"},"step_position":{"type":"integer"},"status":{"type":"string"},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"step_versions":{"type":"array","items":{"type":"object","required":["id","step_id","version","objective","config","is_active","changed_by_user_id","created_at"],"properties":{"id":{"type":"integer"},"step_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}}}}},"feed_sources":{"type":"array","items":{"type":"object","required":["id","feed_id","source_id","status","created_at","sources","feed_source_policies"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"sources":{"type":"object","required":["id","name","status","type"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"type":{"type":"string"},"_count":{}}},"feed_source_policies":{"type":"array","items":{"type":"object","required":["id","feed_id","source_id","status","current_version","created_by_user_id","created_at","feed_source_policy_versions"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"feed_source_policy_versions":{"type":"array","items":{"type":"object","required":["id","policy_id","version","config","is_active","created_at"],"properties":{"id":{"type":"integer"},"policy_id":{"type":"string"},"version":{"type":"integer"},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}}}}}}}},"auto_optimize_enabled":{"type":"boolean"},"version":{"anyOf":[{"type":"object","required":["id","feed_id","version","objective","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"feed_id":{"type":"string"},"version":{"type":"integer"},"objective":{"anyOf":[{"type":"string"},{"type":"null"}]},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid status value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Non-admin caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Feed not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/feeds/{id}/sources":{"post":{"operationId":"attachFeedSource","summary":"Link a source to a feed","tags":["Feeds"],"description":"Attaches a source to the feed. Requires admin role.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Feed ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["sourceId"],"properties":{"sourceId":{"description":"ID of the source to attach to this feed.","type":"string"}}}}}},"responses":{"201":{"description":"Source linked to feed","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","feed_id","source_id","status","created_at"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Non-admin caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Feed or source not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/feeds/{id}/sources/{sourceId}":{"delete":{"operationId":"detachFeedSource","summary":"Unlink a source from a feed","tags":["Feeds"],"description":"Removes the link between a source and a feed. Requires admin role.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Feed ID"},{"name":"sourceId","in":"path","required":true,"schema":{"description":"Source ID","examples":["660e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Source ID"}],"responses":{"200":{"description":"Source unlinked from feed","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","feed_id","source_id","status","created_at"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Non-admin caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Link not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/feed-items":{"get":{"operationId":"listFeedItems","summary":"List feed items with optional filters","tags":["Feeds"],"description":"Returns a paginated list of feed items for the authenticated organization. Supports filtering by feed, outcome, and project.\n\nA feed item is a piece of content as evaluated and interpreted within the scope of a specific feed. Each feed item has a unique ID (format: feeditem-<24hex>).","security":[{"bearerAuth":[]}],"parameters":[{"name":"feedId","in":"query","required":false,"schema":{"description":"Filter by a single feed ID.","type":"string"},"description":"Filter by a single feed ID."},{"name":"feedIds","in":"query","required":false,"schema":{"description":"Filter by a comma-separated set of feed IDs.","type":"string"},"description":"Filter by a comma-separated set of feed IDs."},{"name":"outcome","in":"query","required":false,"schema":{"description":"Filter by outcome. Accepts a single value or comma-separated list. All supplied values must be valid. Valid values: filtered_out, included.","type":"string"},"description":"Filter by outcome. Accepts a single value or comma-separated list. All supplied values must be valid. Valid values: filtered_out, included."},{"name":"projectIds","in":"query","required":false,"schema":{"description":"Filter by a comma-separated set of project IDs.","type":"string"},"description":"Filter by a comma-separated set of project IDs."},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"description":"Maximum number of results to return. Default: 50.","type":"integer"},"description":"Maximum number of results to return. Default: 50."},{"name":"offset","in":"query","required":false,"schema":{"minimum":0,"description":"Number of results to skip for pagination. Default: 0.","type":"integer"},"description":"Number of results to skip for pagination. Default: 0."}],"responses":{"200":{"description":"Paginated list of feed items","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","feed_id","feed_config_version","content_item_id","outcome","summary","filter_reason","idempotency_key","created_at","embedding_model","representation_type","feeds","content_items"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"feed_config_version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"content_item_id":{"type":"string"},"outcome":{"anyOf":[{"type":"string","enum":["filtered_out","included"]},{"type":"null"}]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"filter_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"embedding_model":{"anyOf":[{"type":"string"},{"type":"null"}]},"representation_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"feeds":{"type":"object","required":["id","name","project_id"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"project_id":{"type":"string"}}},"content_items":{"type":"object","required":["id","title","canonical_url","published_at","est_published_at","content_text","first_seen_source_id","sources","acquisition"],"properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"canonical_url":{"type":"string"},"published_at":{"anyOf":[{"description":"ISO 8601 timestamp","type":"string"},{"type":"null"}]},"est_published_at":{"anyOf":[{"description":"Estimated publication date (ISO 8601)","type":"string"},{"type":"null"}]},"content_text":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_seen_source_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"sources":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},{"type":"null"}]},"acquisition":{"anyOf":[{"type":"object","required":["sourceType","acquisitionKind","canonical","discoveredVia"],"properties":{"sourceType":{"type":"string"},"acquisitionKind":{"type":"string"},"canonical":{"type":"object","required":["entityType","url","label"],"properties":{"entityType":{"type":"string"},"url":{"type":"string"},"label":{"type":"string"}}},"discoveredVia":{"anyOf":[{"type":"object","required":["entityType","url","label"],"properties":{"entityType":{"type":"string"},"url":{"type":"string"},"label":{"type":"string"}}},{"type":"null"}]}}},{"type":"null"}]}}}}}},"meta":{"type":"object","required":["requestId","total","limit","offset"],"properties":{"requestId":{"format":"uuid","type":"string"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"400":{"description":"Invalid outcome filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/feed-items/{id}":{"get":{"operationId":"getFeedItem","summary":"Get feed item details","tags":["Feeds"],"description":"Returns full feed item details including content and feed metadata.\n\nA feed item is a piece of content as evaluated and interpreted within the scope of a specific feed. Each feed item has a unique ID (format: feeditem-<24hex>).","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed item ID","type":"string"},"description":"Feed item ID"}],"responses":{"200":{"description":"Feed item details","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","feed_id","feed_config_version","content_item_id","outcome","summary","filter_reason","idempotency_key","created_at","embedding_model","representation_type","feeds","content_items"],"properties":{"id":{"type":"string"},"feed_id":{"type":"string"},"feed_config_version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"content_item_id":{"type":"string"},"outcome":{"anyOf":[{"type":"string","enum":["filtered_out","included"]},{"type":"null"}]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"filter_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"embedding_model":{"anyOf":[{"type":"string"},{"type":"null"}]},"representation_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"feeds":{"type":"object","required":["id","name","project_id"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"project_id":{"type":"string"}}},"content_items":{"type":"object","required":["id","title","canonical_url","published_at","est_published_at","content_text","first_seen_source_id","sources","acquisition"],"properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"canonical_url":{"type":"string"},"published_at":{"anyOf":[{"description":"ISO 8601 timestamp","type":"string"},{"type":"null"}]},"est_published_at":{"anyOf":[{"description":"Estimated publication date (ISO 8601)","type":"string"},{"type":"null"}]},"content_text":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_seen_source_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"sources":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},{"type":"null"}]},"acquisition":{"anyOf":[{"type":"object","required":["sourceType","acquisitionKind","canonical","discoveredVia"],"properties":{"sourceType":{"type":"string"},"acquisitionKind":{"type":"string"},"canonical":{"type":"object","required":["entityType","url","label"],"properties":{"entityType":{"type":"string"},"url":{"type":"string"},"label":{"type":"string"}}},"discoveredVia":{"anyOf":[{"type":"object","required":["entityType","url","label"],"properties":{"entityType":{"type":"string"},"url":{"type":"string"},"label":{"type":"string"}}},{"type":"null"}]}}},{"type":"null"}]}}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Feed item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/digests":{"post":{"operationId":"createDigest","summary":"Create a new digest","tags":["Digests"],"description":"Creates a new digest in the specified project. Config is required and must match the schema for the selected digest_type. Requires admin role.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["projectId","name","config"],"properties":{"projectId":{"description":"ID of the project this digest belongs to.","type":"string"},"name":{"minLength":1,"description":"Human-readable name for the digest.","type":"string"},"config":{"description":"Digest configuration, discriminated by digest_type. See each variant for required and optional fields.","oneOf":[{"additionalProperties":false,"title":"BriefingDigestConfig","type":"object","required":["digest_type","objective"],"properties":{"digest_type":{"description":"Produces a structured briefing with titled sections.","const":"briefing","type":"string"},"objective":{"minLength":1,"description":"High-level goal or purpose of the digest. Guides the AI agent during generation.","type":"string"},"feed_scope":{"description":"Feed IDs to include. An empty array or omission means all feeds in the project.","type":"array","items":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Feed UUID to include in the digest scope.","type":"string"}},"time_window_days":{"minimum":1,"description":"Number of days of content to scan. Default: 7.","type":"integer"},"cron":{"description":"Cron schedule for automatic execution. 5-field format: minute hour day-of-month month day-of-week.","examples":["0 13 * * *","0 */6 * * *"],"type":"string"}}},{"additionalProperties":false,"title":"DatasetDigestConfig","type":"object","required":["digest_type","objective","row_objective","columns"],"properties":{"digest_type":{"description":"Produces a structured dataset table with defined columns, using an AI code agent.","const":"dataset","type":"string"},"objective":{"minLength":1,"description":"High-level goal or purpose of the digest. Guides the AI agent during generation.","type":"string"},"feed_scope":{"description":"Feed IDs to include. An empty array or omission means all feeds in the project.","type":"array","items":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Feed UUID to include in the digest scope.","type":"string"}},"time_window_days":{"minimum":1,"description":"Number of days of content to scan. Default: 7.","type":"integer"},"cron":{"description":"Cron schedule for automatic execution. 5-field format: minute hour day-of-month month day-of-week.","examples":["0 13 * * *","0 */6 * * *"],"type":"string"},"row_objective":{"minLength":1,"description":"Describes what each row in the output dataset represents.","type":"string"},"columns":{"minItems":1,"description":"Column definitions for the output dataset. At least one column is required.","type":"array","items":{"additionalProperties":false,"description":"A single column definition for a dataset digest.","type":"object","required":["name","objective"],"properties":{"name":{"minLength":1,"description":"Column name in the output dataset table.","type":"string"},"objective":{"minLength":1,"description":"Description of what this column captures; guides the AI agent during extraction.","type":"string"}}}},"max_dataset_agent_iterations":{"minimum":1,"maximum":500,"description":"Maximum number of iterations the dataset agent may execute. Default: 200.","type":"integer"}}}],"discriminator":{"propertyName":"digest_type"}},"id":{"description":"Client-supplied ID. If omitted, a UUID is generated server-side.","type":"string"}}}}}},"responses":{"201":{"description":"Newly created digest","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","project_id","name","status","current_version","created_by_user_id","created_at","digest_versions","auto_optimize_enabled","version","health","last_event_at","schedule_status"],"properties":{"id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","archived"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"digest_versions":{"type":"array","items":{"type":"object","required":["id","digest_id","version","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"digest_id":{"type":"string"},"version":{"type":"integer"},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"auto_optimize_enabled":{"type":"boolean"},"version":{"anyOf":[{"type":"object","required":["id","digest_id","version","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"digest_id":{"type":"string"},"version":{"type":"integer"},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule_status":{"anyOf":[{"const":"pending","type":"string"},{"const":"synced","type":"string"},{"const":"failed","type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"get":{"operationId":"listDigests","summary":"List digests with optional filters","tags":["Digests"],"description":"Returns a paginated list of digests for the authenticated organization. Supports filtering by project and status.","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"description":"Maximum number of results to return. Default: 50.","type":"integer"},"description":"Maximum number of results to return. Default: 50."},{"name":"offset","in":"query","required":false,"schema":{"minimum":0,"description":"Number of results to skip for pagination. Default: 0.","type":"integer"},"description":"Number of results to skip for pagination. Default: 0."},{"name":"projectId","in":"query","required":false,"schema":{"description":"Filter digests by project ID.","type":"string"},"description":"Filter digests by project ID."},{"name":"projectIds","in":"query","required":false,"schema":{"description":"Filter digests by a comma-separated set of project IDs.","type":"string"},"description":"Filter digests by a comma-separated set of project IDs."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","paused","archived"]}},{"name":"health","in":"query","required":false,"schema":{"description":"Filter digests by one or more health values. Use a comma-separated list such as \"healthy,error\".","type":"string"},"description":"Filter digests by one or more health values. Use a comma-separated list such as \"healthy,error\"."}],"responses":{"200":{"description":"Paginated list of digests","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","project_id","name","status","current_version","created_by_user_id","created_at","digest_versions","projects","digest_outputs","version","health","last_event_at","schedule_status","project_name","last_output_at"],"properties":{"id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","archived"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"digest_versions":{"type":"array","items":{"type":"object","required":["id","digest_id","version","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"digest_id":{"type":"string"},"version":{"type":"integer"},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"projects":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}},"digest_outputs":{"type":"array","items":{"type":"object","required":["created_at"],"properties":{"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"version":{"anyOf":[{"type":"object","required":["id","digest_id","version","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"digest_id":{"type":"string"},"version":{"type":"integer"},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule_status":{"anyOf":[{"const":"pending","type":"string"},{"const":"synced","type":"string"},{"const":"failed","type":"string"},{"type":"null"}]},"project_name":{"type":"string"},"last_output_at":{"anyOf":[{"type":"string"},{"type":"null"}]}}}},"meta":{"type":"object","required":["requestId","total","limit","offset"],"properties":{"requestId":{"format":"uuid","type":"string"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/digests/{id}":{"get":{"operationId":"getDigest","summary":"Get digest details","tags":["Digests"],"description":"Returns full digest details including current version, health status, and schedule status.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Digest ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Digest ID"}],"responses":{"200":{"description":"Digest details","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","project_id","name","status","current_version","created_by_user_id","created_at","digest_versions","auto_optimize_enabled","version","health","last_event_at","schedule_status"],"properties":{"id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","archived"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"digest_versions":{"type":"array","items":{"type":"object","required":["id","digest_id","version","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"digest_id":{"type":"string"},"version":{"type":"integer"},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"auto_optimize_enabled":{"type":"boolean"},"version":{"anyOf":[{"type":"object","required":["id","digest_id","version","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"digest_id":{"type":"string"},"version":{"type":"integer"},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule_status":{"anyOf":[{"const":"pending","type":"string"},{"const":"synced","type":"string"},{"const":"failed","type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Digest not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"patch":{"operationId":"updateDigest","summary":"Update digest configuration","tags":["Digests"],"description":"Updates digest properties. At least one field must be provided. If config is provided, it must match the schema for the selected digest_type. Requires admin role.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Digest ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Digest ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"minProperties":1,"type":"object","properties":{"name":{"minLength":1,"description":"Updated display name.","type":"string"},"config":{"description":"Digest configuration, discriminated by digest_type. See each variant for required and optional fields.","oneOf":[{"additionalProperties":false,"title":"BriefingDigestConfig","type":"object","required":["digest_type","objective"],"properties":{"digest_type":{"description":"Produces a structured briefing with titled sections.","const":"briefing","type":"string"},"objective":{"minLength":1,"description":"High-level goal or purpose of the digest. Guides the AI agent during generation.","type":"string"},"feed_scope":{"description":"Feed IDs to include. An empty array or omission means all feeds in the project.","type":"array","items":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Feed UUID to include in the digest scope.","type":"string"}},"time_window_days":{"minimum":1,"description":"Number of days of content to scan. Default: 7.","type":"integer"},"cron":{"description":"Cron schedule for automatic execution. 5-field format: minute hour day-of-month month day-of-week.","examples":["0 13 * * *","0 */6 * * *"],"type":"string"}}},{"additionalProperties":false,"title":"DatasetDigestConfig","type":"object","required":["digest_type","objective","row_objective","columns"],"properties":{"digest_type":{"description":"Produces a structured dataset table with defined columns, using an AI code agent.","const":"dataset","type":"string"},"objective":{"minLength":1,"description":"High-level goal or purpose of the digest. Guides the AI agent during generation.","type":"string"},"feed_scope":{"description":"Feed IDs to include. An empty array or omission means all feeds in the project.","type":"array","items":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Feed UUID to include in the digest scope.","type":"string"}},"time_window_days":{"minimum":1,"description":"Number of days of content to scan. Default: 7.","type":"integer"},"cron":{"description":"Cron schedule for automatic execution. 5-field format: minute hour day-of-month month day-of-week.","examples":["0 13 * * *","0 */6 * * *"],"type":"string"},"row_objective":{"minLength":1,"description":"Describes what each row in the output dataset represents.","type":"string"},"columns":{"minItems":1,"description":"Column definitions for the output dataset. At least one column is required.","type":"array","items":{"additionalProperties":false,"description":"A single column definition for a dataset digest.","type":"object","required":["name","objective"],"properties":{"name":{"minLength":1,"description":"Column name in the output dataset table.","type":"string"},"objective":{"minLength":1,"description":"Description of what this column captures; guides the AI agent during extraction.","type":"string"}}}},"max_dataset_agent_iterations":{"minimum":1,"maximum":500,"description":"Maximum number of iterations the dataset agent may execute. Default: 200.","type":"integer"}}}],"discriminator":{"propertyName":"digest_type"}},"changeReason":{"description":"Human-readable reason for the change. Stored in the version audit trail.","type":"string"},"autoOptimizeEnabled":{"description":"Toggle automatic optimization for this digest.","type":"boolean"}}}}}},"responses":{"200":{"description":"Updated digest","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","project_id","name","status","current_version","created_by_user_id","created_at","digest_versions","auto_optimize_enabled","version","health","last_event_at","schedule_status"],"properties":{"id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","archived"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"digest_versions":{"type":"array","items":{"type":"object","required":["id","digest_id","version","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"digest_id":{"type":"string"},"version":{"type":"integer"},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"auto_optimize_enabled":{"type":"boolean"},"version":{"anyOf":[{"type":"object","required":["id","digest_id","version","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"digest_id":{"type":"string"},"version":{"type":"integer"},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule_status":{"anyOf":[{"const":"pending","type":"string"},{"const":"synced","type":"string"},{"const":"failed","type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid body or empty update","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Non-admin caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Digest not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/digests/{id}/status":{"patch":{"operationId":"updateDigestStatus","summary":"Update digest status","tags":["Digests"],"description":"Transitions the digest to a new status. Pausing stops scheduled runs, activating resumes them (with entitlement check), and archiving permanently retires the digest.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Digest ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Digest ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["active","paused","archived"]}}}}}},"responses":{"200":{"description":"Updated digest","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","project_id","name","status","current_version","created_by_user_id","created_at","digest_versions","auto_optimize_enabled","version","health","last_event_at","schedule_status"],"properties":{"id":{"type":"string"},"project_id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","archived"]},"current_version":{"type":"integer"},"created_by_user_id":{"type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"digest_versions":{"type":"array","items":{"type":"object","required":["id","digest_id","version","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"digest_id":{"type":"string"},"version":{"type":"integer"},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}}},"auto_optimize_enabled":{"type":"boolean"},"version":{"anyOf":[{"type":"object","required":["id","digest_id","version","config","is_active","changed_by_user_id","effective_from","created_at"],"properties":{"id":{"type":"integer"},"digest_id":{"type":"string"},"version":{"type":"integer"},"config":{"anyOf":[{},{"type":"null"}]},"is_active":{"type":"boolean"},"changed_by_user_id":{"type":"string"},"effective_from":{"description":"ISO 8601 timestamp","type":"string"},"created_at":{"description":"ISO 8601 timestamp","type":"string"}}},{"type":"null"}]},"health":{"anyOf":[{"const":"healthy","type":"string"},{"const":"error","type":"string"},{"const":"idle","type":"string"},{"const":"running","type":"string"},{"const":"optimizing","type":"string"},{"type":"null"}]},"last_event_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule_status":{"anyOf":[{"const":"pending","type":"string"},{"const":"synced","type":"string"},{"const":"failed","type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid status value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Non-admin caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Digest not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/digests/{id}/trigger":{"post":{"operationId":"triggerDigest","summary":"Trigger digest execution","tags":["Digests"],"description":"Starts a digest execution workflow. The digest must not be archived.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Digest ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Digest ID"}],"responses":{"200":{"description":"Digest workflow triggered","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["workflow_id","digest_id","trigger_type"],"properties":{"workflow_id":{"type":"string"},"digest_id":{"type":"string"},"trigger_type":{"const":"manual","type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Digest not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Digest is archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/digests/{id}/bootstrap":{"post":{"operationId":"bootstrapDigestToFirstOutput","summary":"Bootstrap digest to first output","tags":["Digests"],"description":"Drive an eligible digest scaffold through source testing, upstream refresh, and digest execution to produce the first output artifact.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Digest ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Digest ID"}],"responses":{"202":{"description":"Bootstrap started","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["bootstrapRunId","digestId","source_count","admitted_count","status"],"properties":{"bootstrapRunId":{"type":"string"},"digestId":{"type":"string"},"source_count":{"type":"number"},"admitted_count":{"type":"number"},"status":{"const":"started","type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Digest not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"A bootstrap or digest-generation workflow is already in flight for this digest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Bootstrap rejected (exceeds_source_limit | rejected_admission | no_upstream_sources)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/digests/{id}/bootstrap/{bootstrapRunId}":{"get":{"operationId":"getBootstrapStatus","summary":"Get bootstrap status","tags":["Digests"],"description":"Poll the status of a running bootstrap operation. Returns current phase, progress counts, and terminal state when complete.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"bootstrapRunId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Bootstrap status","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["bootstrapRunId","digestId","phase","sources_tested","sources_test_passed","sources_test_failed","sources_ingested","sources_ingestion_failed","sources_skipped","feed_items_found","started_at"],"properties":{"bootstrapRunId":{"type":"string"},"digestId":{"type":"string"},"phase":{"type":"string","enum":["testing","ingesting","waiting_for_items","digesting","terminal"]},"terminal_state":{"type":"string"},"terminal_reason":{"type":"string"},"sources_tested":{"type":"number"},"sources_test_passed":{"type":"number"},"sources_test_failed":{"type":"number"},"sources_ingested":{"type":"number"},"sources_ingestion_failed":{"type":"number"},"sources_skipped":{"type":"number"},"feed_items_found":{"type":"number"},"digest_output_id":{"type":"string"},"digest_workflow_id":{"type":"string"},"started_at":{"type":"string"},"completed_at":{"type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Bootstrap run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/digest-outputs":{"get":{"operationId":"listDigestOutputs","summary":"List digest outputs","tags":["Digests"],"description":"Returns a paginated list of digest outputs. Supports filtering by digestId and projectIds (comma-separated). The admin-only includePartial flag includes incomplete outputs.","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"description":"Maximum number of results to return. Default: 50.","type":"integer"},"description":"Maximum number of results to return. Default: 50."},{"name":"offset","in":"query","required":false,"schema":{"minimum":0,"description":"Number of results to skip for pagination. Default: 0.","type":"integer"},"description":"Number of results to skip for pagination. Default: 0."},{"name":"digestId","in":"query","required":false,"schema":{"description":"Filter outputs by digest ID.","type":"string"},"description":"Filter outputs by digest ID."},{"name":"projectIds","in":"query","required":false,"schema":{"description":"Comma-separated project IDs to filter by.","type":"string"},"description":"Comma-separated project IDs to filter by."},{"name":"includePartial","in":"query","required":false,"schema":{"description":"Include partial (incomplete) outputs. Admin-only; ignored for non-admin callers.","type":"boolean"},"description":"Include partial (incomplete) outputs. Admin-only; ignored for non-admin callers."},{"name":"status","in":"query","required":false,"schema":{"description":"Filter outputs by status. Defaults to active.","type":"string","enum":["active","archived"]},"description":"Filter outputs by status. Defaults to active."}],"responses":{"200":{"description":"Paginated list of digest outputs","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"title":"DigestOutputListItem","description":"Digest output as returned in list responses. Includes full content payload.","examples":[{"id":"dout-briefing-001","digest_id":"dig-001","digest_config_version":3,"digest_type":"briefing","content":{"type":"briefing","title":"Weekly AI Research Briefing","sections":[{"heading":"Key Developments","body":"Several major labs released new model architectures this week…"},{"heading":"Industry Impact","body":"Enterprise adoption of agentic workflows continues to accelerate…"}],"meta_summary":"A concise weekly digest covering the most significant developments in AI research and deployment.","key_summaries":["New transformer variant achieves state-of-the-art on reasoning benchmarks.","Major cloud providers announce expanded AI infrastructure plans."],"metadata":{}},"is_partial":false,"status":"active","trigger_type":"scheduled","schedule_tick":"2026-04-09T13:00:00Z","manual_request_id":null,"agent_model":"gpt-4o","duration_ms":14200,"created_at":"2026-04-09T13:02:31.000Z","digests":{"id":"dig-001","name":"AI Research Weekly","project_id":"proj-001"}},{"id":"dout-dataset-001","digest_id":"dig-002","digest_config_version":1,"digest_type":"dataset","content":{"type":"dataset","title":"Competitor Feature Matrix","meta_summary":"Structured comparison of competitor product features extracted from public sources.","changelog":"Initial extraction — 12 rows, 4 columns.","row_count":12,"column_names":["company","feature","status","source_url"],"rows":[{"company":"Acme Corp","feature":"SSO","status":"GA","source_url":"https://example.com/acme-sso"}],"s3_workspace_path":"s3://cortex-workspaces/proj-1/dataset-abc/v1"},"is_partial":false,"status":"active","trigger_type":"manual","schedule_tick":null,"manual_request_id":"mreq-abc","agent_model":"gpt-4o","duration_ms":87500,"created_at":"2026-04-08T10:15:00.000Z","digests":{"id":"dig-002","name":"Competitor Tracker","project_id":"proj-002"}}],"type":"object","required":["id","digest_id","digest_config_version","digest_type","is_partial","status","trigger_type","schedule_tick","manual_request_id","agent_model","duration_ms","created_at","digests","content"],"properties":{"id":{"type":"string"},"digest_id":{"type":"string"},"digest_config_version":{"description":"Version of the digest configuration used for this execution.","type":"integer"},"digest_type":{"description":"Discriminator for the content shape. Briefing and dataset are the supported public variants.","type":"string","enum":["briefing","dataset"]},"is_partial":{"type":"boolean"},"status":{"description":"Lifecycle status of this output.","type":"string","enum":["active","archived"]},"trigger_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule_tick":{"anyOf":[{"description":"ISO 8601 timestamp","type":"string"},{"type":"null"}]},"manual_request_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"agent_model":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}]},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"digests":{"type":"object","required":["id","name","project_id"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"project_id":{"type":"string"}}},"content":{"description":"Content payload discriminated by type. Interpretation is driven by digest_type.","oneOf":[{"title":"BriefingContent","description":"Structured briefing output with titled sections.","type":"object","required":["type","title","sections","meta_summary","key_summaries"],"properties":{"type":{"const":"briefing","type":"string"},"title":{"type":"string"},"sections":{"type":"array","items":{"type":"object","required":["heading","body"],"properties":{"heading":{"type":"string"},"body":{"type":"string"}}}},"meta_summary":{"type":"string"},"key_summaries":{"type":"array","items":{"type":"string"}},"metadata":{"additionalProperties":true,"type":"object","properties":{}}}},{"title":"DatasetContent","description":"Structured dataset output with tabular rows and column metadata.","type":"object","required":["type","title","meta_summary","changelog","row_count","column_names","rows","s3_workspace_path"],"properties":{"type":{"const":"dataset","type":"string"},"title":{"type":"string"},"meta_summary":{"type":"string"},"changelog":{"type":"string"},"row_count":{"type":"integer"},"column_names":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"additionalProperties":true,"type":"object","properties":{}}},"s3_workspace_path":{"type":"string"}}}],"discriminator":{"propertyName":"type"}}}}},"meta":{"type":"object","required":["requestId","total","limit","offset"],"properties":{"requestId":{"format":"uuid","type":"string"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/digest-outputs/{id}":{"get":{"operationId":"getDigestOutput","summary":"Get digest output details","tags":["Digests"],"description":"Returns a specific digest output, including generated content, execution metadata, and the parent digest reference. The content shape is discriminated by digest_type — see BriefingContent and DatasetContent.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Digest output ID","type":"string"},"description":"Digest output ID"}],"responses":{"200":{"description":"Digest output details with content","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"title":"DigestOutputDetail","description":"Full digest output including content payload. The content shape is determined by digest_type.","examples":[{"id":"dout-briefing-001","digest_id":"dig-001","digest_config_version":3,"digest_type":"briefing","content":{"type":"briefing","title":"Weekly AI Research Briefing","sections":[{"heading":"Key Developments","body":"Several major labs released new model architectures this week…"},{"heading":"Industry Impact","body":"Enterprise adoption of agentic workflows continues to accelerate…"}],"meta_summary":"A concise weekly digest covering the most significant developments in AI research and deployment.","key_summaries":["New transformer variant achieves state-of-the-art on reasoning benchmarks.","Major cloud providers announce expanded AI infrastructure plans."],"metadata":{}},"is_partial":false,"status":"active","trigger_type":"scheduled","schedule_tick":"2026-04-09T13:00:00Z","manual_request_id":null,"agent_model":"gpt-4o","duration_ms":14200,"created_at":"2026-04-09T13:02:31.000Z","digests":{"id":"dig-001","name":"AI Research Weekly","project_id":"proj-001"}},{"id":"dout-dataset-001","digest_id":"dig-002","digest_config_version":1,"digest_type":"dataset","content":{"type":"dataset","title":"Competitor Feature Matrix","meta_summary":"Structured comparison of competitor product features extracted from public sources.","changelog":"Initial extraction — 12 rows, 4 columns.","row_count":12,"column_names":["company","feature","status","source_url"],"rows":[{"company":"Acme Corp","feature":"SSO","status":"GA","source_url":"https://example.com/acme-sso"}],"s3_workspace_path":"s3://cortex-workspaces/proj-1/dataset-abc/v1"},"is_partial":false,"status":"active","trigger_type":"manual","schedule_tick":null,"manual_request_id":"mreq-abc","agent_model":"gpt-4o","duration_ms":87500,"created_at":"2026-04-08T10:15:00.000Z","digests":{"id":"dig-002","name":"Competitor Tracker","project_id":"proj-002"}}],"type":"object","required":["id","digest_id","digest_config_version","digest_type","is_partial","status","trigger_type","schedule_tick","manual_request_id","agent_model","duration_ms","created_at","digests","content"],"properties":{"id":{"type":"string"},"digest_id":{"type":"string"},"digest_config_version":{"description":"Version of the digest configuration used for this execution.","type":"integer"},"digest_type":{"description":"Discriminator for the content shape. Briefing and dataset are the supported public variants.","type":"string","enum":["briefing","dataset"]},"is_partial":{"type":"boolean"},"status":{"description":"Lifecycle status of this output.","type":"string","enum":["active","archived"]},"trigger_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule_tick":{"anyOf":[{"description":"ISO 8601 timestamp","type":"string"},{"type":"null"}]},"manual_request_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"agent_model":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}]},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"digests":{"type":"object","required":["id","name","project_id"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"project_id":{"type":"string"}}},"content":{"description":"Content payload discriminated by type. Interpretation is driven by digest_type.","oneOf":[{"title":"BriefingContent","description":"Structured briefing output with titled sections.","type":"object","required":["type","title","sections","meta_summary","key_summaries"],"properties":{"type":{"const":"briefing","type":"string"},"title":{"type":"string"},"sections":{"type":"array","items":{"type":"object","required":["heading","body"],"properties":{"heading":{"type":"string"},"body":{"type":"string"}}}},"meta_summary":{"type":"string"},"key_summaries":{"type":"array","items":{"type":"string"}},"metadata":{"additionalProperties":true,"type":"object","properties":{}}}},{"title":"DatasetContent","description":"Structured dataset output with tabular rows and column metadata.","type":"object","required":["type","title","meta_summary","changelog","row_count","column_names","rows","s3_workspace_path"],"properties":{"type":{"const":"dataset","type":"string"},"title":{"type":"string"},"meta_summary":{"type":"string"},"changelog":{"type":"string"},"row_count":{"type":"integer"},"column_names":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"additionalProperties":true,"type":"object","properties":{}}},"s3_workspace_path":{"type":"string"}}}],"discriminator":{"propertyName":"type"}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Output not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/digest-outputs/{id}/status":{"patch":{"operationId":"updateDigestOutputStatus","summary":"Update digest output status (archive/restore)","tags":["Digests"],"description":"Archives or restores a specific digest output. Archived outputs are excluded from default list queries but remain accessible by direct ID.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Digest output ID","type":"string"},"description":"Digest output ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["active","archived"]}}}}}},"responses":{"200":{"description":"Updated digest output","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"title":"DigestOutputDetail","description":"Full digest output including content payload. The content shape is determined by digest_type.","examples":[{"id":"dout-briefing-001","digest_id":"dig-001","digest_config_version":3,"digest_type":"briefing","content":{"type":"briefing","title":"Weekly AI Research Briefing","sections":[{"heading":"Key Developments","body":"Several major labs released new model architectures this week…"},{"heading":"Industry Impact","body":"Enterprise adoption of agentic workflows continues to accelerate…"}],"meta_summary":"A concise weekly digest covering the most significant developments in AI research and deployment.","key_summaries":["New transformer variant achieves state-of-the-art on reasoning benchmarks.","Major cloud providers announce expanded AI infrastructure plans."],"metadata":{}},"is_partial":false,"status":"active","trigger_type":"scheduled","schedule_tick":"2026-04-09T13:00:00Z","manual_request_id":null,"agent_model":"gpt-4o","duration_ms":14200,"created_at":"2026-04-09T13:02:31.000Z","digests":{"id":"dig-001","name":"AI Research Weekly","project_id":"proj-001"}},{"id":"dout-dataset-001","digest_id":"dig-002","digest_config_version":1,"digest_type":"dataset","content":{"type":"dataset","title":"Competitor Feature Matrix","meta_summary":"Structured comparison of competitor product features extracted from public sources.","changelog":"Initial extraction — 12 rows, 4 columns.","row_count":12,"column_names":["company","feature","status","source_url"],"rows":[{"company":"Acme Corp","feature":"SSO","status":"GA","source_url":"https://example.com/acme-sso"}],"s3_workspace_path":"s3://cortex-workspaces/proj-1/dataset-abc/v1"},"is_partial":false,"status":"active","trigger_type":"manual","schedule_tick":null,"manual_request_id":"mreq-abc","agent_model":"gpt-4o","duration_ms":87500,"created_at":"2026-04-08T10:15:00.000Z","digests":{"id":"dig-002","name":"Competitor Tracker","project_id":"proj-002"}}],"type":"object","required":["id","digest_id","digest_config_version","digest_type","is_partial","status","trigger_type","schedule_tick","manual_request_id","agent_model","duration_ms","created_at","digests","content"],"properties":{"id":{"type":"string"},"digest_id":{"type":"string"},"digest_config_version":{"description":"Version of the digest configuration used for this execution.","type":"integer"},"digest_type":{"description":"Discriminator for the content shape. Briefing and dataset are the supported public variants.","type":"string","enum":["briefing","dataset"]},"is_partial":{"type":"boolean"},"status":{"description":"Lifecycle status of this output.","type":"string","enum":["active","archived"]},"trigger_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"schedule_tick":{"anyOf":[{"description":"ISO 8601 timestamp","type":"string"},{"type":"null"}]},"manual_request_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"agent_model":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}]},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"digests":{"type":"object","required":["id","name","project_id"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"project_id":{"type":"string"}}},"content":{"description":"Content payload discriminated by type. Interpretation is driven by digest_type.","oneOf":[{"title":"BriefingContent","description":"Structured briefing output with titled sections.","type":"object","required":["type","title","sections","meta_summary","key_summaries"],"properties":{"type":{"const":"briefing","type":"string"},"title":{"type":"string"},"sections":{"type":"array","items":{"type":"object","required":["heading","body"],"properties":{"heading":{"type":"string"},"body":{"type":"string"}}}},"meta_summary":{"type":"string"},"key_summaries":{"type":"array","items":{"type":"string"}},"metadata":{"additionalProperties":true,"type":"object","properties":{}}}},{"title":"DatasetContent","description":"Structured dataset output with tabular rows and column metadata.","type":"object","required":["type","title","meta_summary","changelog","row_count","column_names","rows","s3_workspace_path"],"properties":{"type":{"const":"dataset","type":"string"},"title":{"type":"string"},"meta_summary":{"type":"string"},"changelog":{"type":"string"},"row_count":{"type":"integer"},"column_names":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"additionalProperties":true,"type":"object","properties":{}}},"s3_workspace_path":{"type":"string"}}}],"discriminator":{"propertyName":"type"}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid status value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Output not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/processing-events":{"get":{"operationId":"listProcessingEvents","summary":"List processing events with filters","tags":["Processing Events"],"description":"Returns a paginated list of processing events scoped to the authenticated organization. Supports filtering by entity type, source, feed, digest, project, event type, and status.","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"description":"Maximum number of results to return. Default: 50.","type":"integer"},"description":"Maximum number of results to return. Default: 50."},{"name":"offset","in":"query","required":false,"schema":{"minimum":0,"description":"Number of results to skip for pagination. Default: 0.","type":"integer"},"description":"Number of results to skip for pagination. Default: 0."},{"name":"entityType","in":"query","required":false,"schema":{"description":"Filter events by entity type when no specific entity ID is selected.","type":"string","enum":["source","feed","digest"]},"description":"Filter events by entity type when no specific entity ID is selected."},{"name":"sourceId","in":"query","required":false,"schema":{"description":"Filter events by source ID.","type":"string"},"description":"Filter events by source ID."},{"name":"feedId","in":"query","required":false,"schema":{"description":"Filter events by feed ID.","type":"string"},"description":"Filter events by feed ID."},{"name":"digestId","in":"query","required":false,"schema":{"description":"Filter events by digest ID.","type":"string"},"description":"Filter events by digest ID."},{"name":"projectId","in":"query","required":false,"schema":{"description":"Filter events by project ID.","type":"string"},"description":"Filter events by project ID."},{"name":"eventType","in":"query","required":false,"schema":{"description":"Pipeline event type. Filter by a single value.","type":"string","enum":["workflow_started","workflow_terminal","source_auto_paused","source_fetch","source_extract","source_extract_page","source_dispatch","feed_filter","feed_summarize","feed_persist","feed_embed","digest_materialize","digest_skipped_empty_scope","digest_agent_error","digest_link_validation","dataset_agent_started","dataset_agent_completed","dataset_agent_failed","schedule_lifecycle"]},"description":"Pipeline event type. Filter by a single value."},{"name":"status","in":"query","required":false,"schema":{"description":"Event outcome status. Filter by a single value.","type":"string","enum":["started","completed","failed","skipped","created","extracted","already_done","upgraded","warning","paused"]},"description":"Event outcome status. Filter by a single value."}],"responses":{"200":{"description":"Paginated list of processing events","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","source_id","feed_id","digest_id","content_item_id","project_id","event_type","activity","status","status_detail_code","status_detail_message","failure_summary","created_at","org_id","source_name","feed_name","digest_name","content_item_title","project_name"],"properties":{"id":{"type":"string"},"source_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"feed_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"digest_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"content_item_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"event_type":{"type":"string"},"activity":{"type":"string"},"status":{"type":"string"},"status_detail_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"status_detail_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"failure_summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"org_id":{"type":"string"},"source_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"feed_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"digest_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"content_item_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"project_name":{"anyOf":[{"type":"string"},{"type":"null"}]}}}},"meta":{"type":"object","required":["requestId","total","limit","offset"],"properties":{"requestId":{"format":"uuid","type":"string"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/feedback":{"post":{"operationId":"createFeedback","summary":"Create a feedback record","tags":["Feedback"],"description":"Submit quality feedback on a digest output, feed item, or chat response. Specify the feedback kind (thumbs, likert, or text), the target surface, and the appropriate value field for the chosen kind. Lineage fields (digestId, feedId, projectId, config versions) are optional and verified server-side for non-chat surfaces.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["kind","surface"],"properties":{"kind":{"type":"string","enum":["thumbs","likert","text"]},"surface":{"type":"string","enum":["digest_output","feed_item","chat"]},"valueBool":{"type":"boolean"},"valueInt":{"minimum":1,"maximum":5,"type":"integer"},"valueText":{"minLength":1,"type":"string"},"digestOutputId":{"minLength":1,"type":"string"},"feedItemId":{"minLength":1,"type":"string"},"excerptText":{"type":"string"},"contentItemId":{"type":"string"},"digestId":{"type":"string"},"feedId":{"type":"string"},"projectId":{"type":"string"},"digestConfigVersion":{"type":"integer"},"feedConfigVersion":{"type":"integer"},"workflowRunId":{"type":"string"},"modelId":{"type":"string"}}}}}},"responses":{"201":{"description":"Feedback record created","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","orgId","userId","kind","surface","valueBool","valueInt","valueText","excerptText","digestOutputId","feedItemId","contentItemId","digestId","feedId","projectId","digestConfigVersion","feedConfigVersion","workflowRunId","modelId","createdAt"],"properties":{"id":{"type":"string"},"orgId":{"type":"string"},"userId":{"type":"string"},"kind":{"type":"string","enum":["thumbs","likert","text"]},"surface":{"type":"string","enum":["digest_output","feed_item","chat"]},"valueBool":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"valueInt":{"anyOf":[{"type":"integer"},{"type":"null"}]},"valueText":{"anyOf":[{"type":"string"},{"type":"null"}]},"excerptText":{"anyOf":[{"type":"string"},{"type":"null"}]},"digestOutputId":{"anyOf":[{"type":"string"},{"type":"null"}]},"feedItemId":{"anyOf":[{"type":"string"},{"type":"null"}]},"contentItemId":{"anyOf":[{"type":"string"},{"type":"null"}]},"digestId":{"anyOf":[{"type":"string"},{"type":"null"}]},"feedId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"digestConfigVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"feedConfigVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workflowRunId":{"anyOf":[{"type":"string"},{"type":"null"}]},"modelId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"description":"ISO 8601 timestamp","type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid body, kind-value mismatch, missing target, contradictory lineage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Referenced target entity not found or belongs to another org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"get":{"operationId":"listFeedback","summary":"List feedback records with filters","tags":["Feedback"],"description":"Retrieve a paginated list of feedback records for the current organization. Filter by feedback kind, surface type, target entity IDs, config versions, or creation date range. Returns records sorted by creation time.","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"default":50,"type":"integer"}},{"name":"offset","in":"query","required":false,"schema":{"minimum":0,"default":0,"type":"integer"}},{"name":"surface","in":"query","required":false,"schema":{"type":"string","enum":["digest_output","feed_item","chat"]}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["thumbs","likert","text"]}},{"name":"digestOutputId","in":"query","required":false,"schema":{"minLength":1,"type":"string"}},{"name":"feedItemId","in":"query","required":false,"schema":{"minLength":1,"type":"string"}},{"name":"digestId","in":"query","required":false,"schema":{"minLength":1,"type":"string"}},{"name":"feedId","in":"query","required":false,"schema":{"minLength":1,"type":"string"}},{"name":"projectId","in":"query","required":false,"schema":{"minLength":1,"type":"string"}},{"name":"createdAfter","in":"query","required":false,"schema":{"format":"date-time","type":"string"}},{"name":"createdBefore","in":"query","required":false,"schema":{"format":"date-time","type":"string"}},{"name":"digestConfigVersion","in":"query","required":false,"schema":{"minimum":1,"type":"integer"}},{"name":"feedConfigVersion","in":"query","required":false,"schema":{"minimum":1,"type":"integer"}}],"responses":{"200":{"description":"Paginated feedback records","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","orgId","userId","kind","surface","valueBool","valueInt","valueText","excerptText","digestOutputId","feedItemId","contentItemId","digestId","feedId","projectId","digestConfigVersion","feedConfigVersion","workflowRunId","modelId","createdAt"],"properties":{"id":{"type":"string"},"orgId":{"type":"string"},"userId":{"type":"string"},"kind":{"type":"string","enum":["thumbs","likert","text"]},"surface":{"type":"string","enum":["digest_output","feed_item","chat"]},"valueBool":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"valueInt":{"anyOf":[{"type":"integer"},{"type":"null"}]},"valueText":{"anyOf":[{"type":"string"},{"type":"null"}]},"excerptText":{"anyOf":[{"type":"string"},{"type":"null"}]},"digestOutputId":{"anyOf":[{"type":"string"},{"type":"null"}]},"feedItemId":{"anyOf":[{"type":"string"},{"type":"null"}]},"contentItemId":{"anyOf":[{"type":"string"},{"type":"null"}]},"digestId":{"anyOf":[{"type":"string"},{"type":"null"}]},"feedId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"digestConfigVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"feedConfigVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workflowRunId":{"anyOf":[{"type":"string"},{"type":"null"}]},"modelId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"description":"ISO 8601 timestamp","type":"string"}}}},"meta":{"type":"object","required":["requestId","total","limit","offset"],"properties":{"requestId":{"format":"uuid","type":"string"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"400":{"description":"Invalid filter values, contradictory filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/feedback/{id}":{"get":{"operationId":"getFeedback","summary":"Get a feedback record by ID","tags":["Feedback"],"description":"Retrieve a single feedback record by its ID. Returns the full record including kind, surface, value, lineage references, and timestamps. Returns 404 if the record does not exist or belongs to a different organization.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feedback record ID","type":"string"},"description":"Feedback record ID"}],"responses":{"200":{"description":"Feedback record","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","orgId","userId","kind","surface","valueBool","valueInt","valueText","excerptText","digestOutputId","feedItemId","contentItemId","digestId","feedId","projectId","digestConfigVersion","feedConfigVersion","workflowRunId","modelId","createdAt"],"properties":{"id":{"type":"string"},"orgId":{"type":"string"},"userId":{"type":"string"},"kind":{"type":"string","enum":["thumbs","likert","text"]},"surface":{"type":"string","enum":["digest_output","feed_item","chat"]},"valueBool":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"valueInt":{"anyOf":[{"type":"integer"},{"type":"null"}]},"valueText":{"anyOf":[{"type":"string"},{"type":"null"}]},"excerptText":{"anyOf":[{"type":"string"},{"type":"null"}]},"digestOutputId":{"anyOf":[{"type":"string"},{"type":"null"}]},"feedItemId":{"anyOf":[{"type":"string"},{"type":"null"}]},"contentItemId":{"anyOf":[{"type":"string"},{"type":"null"}]},"digestId":{"anyOf":[{"type":"string"},{"type":"null"}]},"feedId":{"anyOf":[{"type":"string"},{"type":"null"}]},"projectId":{"anyOf":[{"type":"string"},{"type":"null"}]},"digestConfigVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"feedConfigVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"workflowRunId":{"anyOf":[{"type":"string"},{"type":"null"}]},"modelId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"description":"ISO 8601 timestamp","type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Authenticated but no active org or insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Feedback record not found (includes foreign-org cases)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/feeds/{id}/optimization":{"post":{"operationId":"triggerFeedOptimization","summary":"Trigger a manual optimization run for a feed.","tags":["Feeds","Optimization"],"description":"Start a new optimization run for the specified feed. The run analyzes accumulated feedback and generates an optimized patch revision. Returns 409 if a run is already in progress for this target.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed or Digest ID","type":"string"},"description":"Feed or Digest ID"}],"responses":{"201":{"description":"Optimization run created and workflow dispatched.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","targetId","targetType","status","triggerType","triggeredByUserId","strategyName","strategyVersion","feedbackCount","producedRevisionId","producedRevisionVersion","createdAt","completedAt"],"properties":{"id":{"type":"string"},"targetId":{"type":"string"},"targetType":{"type":"string","enum":["feed","digest"]},"status":{"type":"string"},"triggerType":{"type":"string","enum":["manual","automatic"]},"triggeredByUserId":{"anyOf":[{"type":"string"},{"type":"null"}]},"strategyName":{"type":"string"},"strategyVersion":{"type":"string"},"feedbackCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"producedRevisionId":{"anyOf":[{"type":"number"},{"type":"null"}]},"producedRevisionVersion":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string"},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Insufficient feedback or target not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Target entity not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"An optimization run is already in-flight for this target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"get":{"operationId":"getFeedOptimizationHistory","summary":"Unified optimization history for a feed.","tags":["Feeds","Optimization"],"description":"Retrieve the interleaved timeline of optimization runs and patch revision activations for the specified feed. Events are returned in reverse chronological order with cursor-based pagination.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed or Digest ID","type":"string"},"description":"Feed or Digest ID"},{"name":"limit","in":"query","required":false,"schema":{"default":20,"minimum":1,"maximum":100,"type":"number"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Interleaved run and revision events.","content":{"application/json":{"schema":{"type":"object","required":["events","nextCursor"],"properties":{"events":{"type":"array","items":{"type":"object","required":["type","timestamp"],"properties":{"type":{"type":"string","enum":["run","revision_activated","revision_deactivated"]},"run":{"type":"object","required":["id","targetId","targetType","status","triggerType","triggeredByUserId","strategyName","strategyVersion","feedbackCount","producedRevisionId","producedRevisionVersion","createdAt","completedAt"],"properties":{"id":{"type":"string"},"targetId":{"type":"string"},"targetType":{"type":"string","enum":["feed","digest"]},"status":{"type":"string"},"triggerType":{"type":"string","enum":["manual","automatic"]},"triggeredByUserId":{"anyOf":[{"type":"string"},{"type":"null"}]},"strategyName":{"type":"string"},"strategyVersion":{"type":"string"},"feedbackCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"producedRevisionId":{"anyOf":[{"type":"number"},{"type":"null"}]},"producedRevisionVersion":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string"},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"revision":{"type":"object","required":["id","version","provenance","generatedAgainstConfigVersion","changedByUserId"],"properties":{"id":{"type":"number"},"version":{"type":"number"},"provenance":{"type":"string"},"generatedAgainstConfigVersion":{"type":"number"},"changedByUserId":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"timestamp":{"type":"string"}}}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"404":{"description":"Target entity not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/feeds/{id}/optimization/active":{"get":{"operationId":"getFeedActivePatch","summary":"Get the currently active optimization patch revision for a feed.","tags":["Feeds","Optimization"],"description":"Retrieve the active patch revision for the specified feed, including its directives payload, rendered text, provenance, and config staleness indicator. Returns null if no patch is currently active.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed or Digest ID","type":"string"},"description":"Feed or Digest ID"}],"responses":{"200":{"description":"Active patch revision or null.","content":{"application/json":{"schema":{"type":"object","required":["revision"],"properties":{"revision":{"anyOf":[{"type":"object","required":["id","version","payload","renderedText","provenance","generatedByRunId","generatedAgainstConfigVersion","currentConfigVersion","isStaleConfig","activatedAt","createdAt"],"properties":{"id":{"type":"number"},"version":{"type":"number"},"payload":{"type":"object","required":["format_version","directives"],"properties":{"format_version":{"const":1,"type":"number"},"directives":{"type":"array","items":{"type":"object","required":["position","instruction"],"properties":{"position":{"type":"number"},"instruction":{"type":"string"}}}}}},"renderedText":{"type":"string"},"provenance":{"type":"string"},"generatedByRunId":{"anyOf":[{"type":"string"},{"type":"null"}]},"generatedAgainstConfigVersion":{"type":"number"},"currentConfigVersion":{"type":"number"},"isStaleConfig":{"type":"boolean"},"activatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}}},{"type":"null"}]}}}}}},"404":{"description":"Target entity not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"patch":{"operationId":"editFeedActivePatch","summary":"Edit the currently active optimization patch for a feed.","tags":["Feeds","Optimization"],"description":"Replace the directives on the active patch revision for the specified feed. Creates a new revision with manual_edit provenance. Requires an active patch to exist. Provide 1–10 directives with position and instruction fields.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed or Digest ID","type":"string"},"description":"Feed or Digest ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["directives"],"properties":{"directives":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","required":["position","instruction"],"properties":{"position":{"type":"number"},"instruction":{"type":"string"}}}}}}}}},"responses":{"201":{"description":"New revision created with manual_edit provenance.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","version","payload","renderedText","provenance","generatedByRunId","generatedAgainstConfigVersion","isActive","changedByUserId","activatedAt","deactivatedAt","createdAt"],"properties":{"id":{"type":"number"},"version":{"type":"number"},"payload":{"type":"object","required":["format_version","directives"],"properties":{"format_version":{"const":1,"type":"number"},"directives":{"type":"array","items":{"type":"object","required":["position","instruction"],"properties":{"position":{"type":"number"},"instruction":{"type":"string"}}}}}},"renderedText":{"type":"string"},"provenance":{"type":"string"},"generatedByRunId":{"anyOf":[{"type":"string"},{"type":"null"}]},"generatedAgainstConfigVersion":{"type":"number"},"isActive":{"type":"boolean"},"changedByUserId":{"anyOf":[{"type":"string"},{"type":"null"}]},"activatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"deactivatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Payload fails validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"No active patch exists to edit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/feeds/{id}/optimization/revisions":{"get":{"operationId":"listFeedRevisions","summary":"List all patch revisions for a feed.","tags":["Feeds","Optimization"],"description":"Retrieve a paginated list of all optimization patch revisions for the specified feed. Returns metadata including version, provenance, active status, and timestamps. Use cursor-based pagination for large revision histories.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed or Digest ID","type":"string"},"description":"Feed or Digest ID"},{"name":"limit","in":"query","required":false,"schema":{"default":20,"minimum":1,"maximum":100,"type":"number"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Metadata-only revision list.","content":{"application/json":{"schema":{"type":"object","required":["revisions","nextCursor"],"properties":{"revisions":{"type":"array","items":{"type":"object","required":["id","version","payload","provenance","isActive","generatedAgainstConfigVersion","changedByUserId","activatedAt","deactivatedAt","createdAt"],"properties":{"id":{"type":"number"},"version":{"type":"number"},"payload":{"anyOf":[{"type":"object","patternProperties":{"^(.*)$":{}}},{"type":"null"}]},"provenance":{"type":"string"},"isActive":{"type":"boolean"},"generatedAgainstConfigVersion":{"type":"number"},"changedByUserId":{"anyOf":[{"type":"string"},{"type":"null"}]},"activatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"deactivatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}}}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"404":{"description":"Target entity not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/feeds/{id}/optimization/revisions/{revisionId}/rollback":{"post":{"operationId":"rollbackFeedRevision","summary":"Roll back to a specific prior patch revision for a feed.","tags":["Feeds","Optimization"],"description":"Reactivate a previously used patch revision for the specified feed, deactivating the currently active revision. Returns 409 if the target revision is already active.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed or Digest ID","type":"string"},"description":"Feed or Digest ID"},{"name":"revisionId","in":"path","required":true,"schema":{"description":"Revision ID","type":"string"},"description":"Revision ID"}],"responses":{"200":{"description":"Target revision reactivated.","content":{"application/json":{"schema":{"type":"object","required":["revision","rollbackEvent"],"properties":{"revision":{"type":"object","required":["id","version","payload","provenance","isActive","generatedAgainstConfigVersion","changedByUserId","activatedAt","deactivatedAt","createdAt"],"properties":{"id":{"type":"number"},"version":{"type":"number"},"payload":{"anyOf":[{"type":"object","patternProperties":{"^(.*)$":{}}},{"type":"null"}]},"provenance":{"type":"string"},"isActive":{"type":"boolean"},"generatedAgainstConfigVersion":{"type":"number"},"changedByUserId":{"anyOf":[{"type":"string"},{"type":"null"}]},"activatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"deactivatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}}},"rollbackEvent":{"type":"object","required":["previousActiveRevisionId","rolledBackByUserId"],"properties":{"previousActiveRevisionId":{"anyOf":[{"type":"number"},{"type":"null"}]},"rolledBackByUserId":{"type":"string"}}}}}}}},"404":{"description":"Revision not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Target revision is already active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/digests/{id}/optimization":{"post":{"operationId":"triggerDigestOptimization","summary":"Trigger a manual optimization run for a digest.","tags":["Digests","Optimization"],"description":"Start a new optimization run for the specified digest. The run analyzes accumulated feedback and generates an optimized patch revision. Returns 409 if a run is already in progress for this target.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed or Digest ID","type":"string"},"description":"Feed or Digest ID"}],"responses":{"201":{"description":"Optimization run created and workflow dispatched.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","targetId","targetType","status","triggerType","triggeredByUserId","strategyName","strategyVersion","feedbackCount","producedRevisionId","producedRevisionVersion","createdAt","completedAt"],"properties":{"id":{"type":"string"},"targetId":{"type":"string"},"targetType":{"type":"string","enum":["feed","digest"]},"status":{"type":"string"},"triggerType":{"type":"string","enum":["manual","automatic"]},"triggeredByUserId":{"anyOf":[{"type":"string"},{"type":"null"}]},"strategyName":{"type":"string"},"strategyVersion":{"type":"string"},"feedbackCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"producedRevisionId":{"anyOf":[{"type":"number"},{"type":"null"}]},"producedRevisionVersion":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string"},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Insufficient feedback or target not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Target entity not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"An optimization run is already in-flight for this target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"get":{"operationId":"getDigestOptimizationHistory","summary":"Unified optimization history for a digest.","tags":["Digests","Optimization"],"description":"Retrieve the interleaved timeline of optimization runs and patch revision activations for the specified digest. Events are returned in reverse chronological order with cursor-based pagination.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed or Digest ID","type":"string"},"description":"Feed or Digest ID"},{"name":"limit","in":"query","required":false,"schema":{"default":20,"minimum":1,"maximum":100,"type":"number"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Interleaved run and revision events.","content":{"application/json":{"schema":{"type":"object","required":["events","nextCursor"],"properties":{"events":{"type":"array","items":{"type":"object","required":["type","timestamp"],"properties":{"type":{"type":"string","enum":["run","revision_activated","revision_deactivated"]},"run":{"type":"object","required":["id","targetId","targetType","status","triggerType","triggeredByUserId","strategyName","strategyVersion","feedbackCount","producedRevisionId","producedRevisionVersion","createdAt","completedAt"],"properties":{"id":{"type":"string"},"targetId":{"type":"string"},"targetType":{"type":"string","enum":["feed","digest"]},"status":{"type":"string"},"triggerType":{"type":"string","enum":["manual","automatic"]},"triggeredByUserId":{"anyOf":[{"type":"string"},{"type":"null"}]},"strategyName":{"type":"string"},"strategyVersion":{"type":"string"},"feedbackCount":{"anyOf":[{"type":"number"},{"type":"null"}]},"producedRevisionId":{"anyOf":[{"type":"number"},{"type":"null"}]},"producedRevisionVersion":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string"},"completedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"revision":{"type":"object","required":["id","version","provenance","generatedAgainstConfigVersion","changedByUserId"],"properties":{"id":{"type":"number"},"version":{"type":"number"},"provenance":{"type":"string"},"generatedAgainstConfigVersion":{"type":"number"},"changedByUserId":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"timestamp":{"type":"string"}}}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"404":{"description":"Target entity not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/digests/{id}/optimization/active":{"get":{"operationId":"getDigestActivePatch","summary":"Get the currently active optimization patch revision for a digest.","tags":["Digests","Optimization"],"description":"Retrieve the active patch revision for the specified digest, including its directives payload, rendered text, provenance, and config staleness indicator. Returns null if no patch is currently active.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed or Digest ID","type":"string"},"description":"Feed or Digest ID"}],"responses":{"200":{"description":"Active patch revision or null.","content":{"application/json":{"schema":{"type":"object","required":["revision"],"properties":{"revision":{"anyOf":[{"type":"object","required":["id","version","payload","renderedText","provenance","generatedByRunId","generatedAgainstConfigVersion","currentConfigVersion","isStaleConfig","activatedAt","createdAt"],"properties":{"id":{"type":"number"},"version":{"type":"number"},"payload":{"type":"object","required":["format_version","directives"],"properties":{"format_version":{"const":1,"type":"number"},"directives":{"type":"array","items":{"type":"object","required":["position","instruction"],"properties":{"position":{"type":"number"},"instruction":{"type":"string"}}}}}},"renderedText":{"type":"string"},"provenance":{"type":"string"},"generatedByRunId":{"anyOf":[{"type":"string"},{"type":"null"}]},"generatedAgainstConfigVersion":{"type":"number"},"currentConfigVersion":{"type":"number"},"isStaleConfig":{"type":"boolean"},"activatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}}},{"type":"null"}]}}}}}},"404":{"description":"Target entity not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"patch":{"operationId":"editDigestActivePatch","summary":"Edit the currently active optimization patch for a digest.","tags":["Digests","Optimization"],"description":"Replace the directives on the active patch revision for the specified digest. Creates a new revision with manual_edit provenance. Requires an active patch to exist. Provide 1–10 directives with position and instruction fields.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed or Digest ID","type":"string"},"description":"Feed or Digest ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["directives"],"properties":{"directives":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","required":["position","instruction"],"properties":{"position":{"type":"number"},"instruction":{"type":"string"}}}}}}}}},"responses":{"201":{"description":"New revision created with manual_edit provenance.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","version","payload","renderedText","provenance","generatedByRunId","generatedAgainstConfigVersion","isActive","changedByUserId","activatedAt","deactivatedAt","createdAt"],"properties":{"id":{"type":"number"},"version":{"type":"number"},"payload":{"type":"object","required":["format_version","directives"],"properties":{"format_version":{"const":1,"type":"number"},"directives":{"type":"array","items":{"type":"object","required":["position","instruction"],"properties":{"position":{"type":"number"},"instruction":{"type":"string"}}}}}},"renderedText":{"type":"string"},"provenance":{"type":"string"},"generatedByRunId":{"anyOf":[{"type":"string"},{"type":"null"}]},"generatedAgainstConfigVersion":{"type":"number"},"isActive":{"type":"boolean"},"changedByUserId":{"anyOf":[{"type":"string"},{"type":"null"}]},"activatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"deactivatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Payload fails validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"No active patch exists to edit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/digests/{id}/optimization/revisions":{"get":{"operationId":"listDigestRevisions","summary":"List all patch revisions for a digest.","tags":["Digests","Optimization"],"description":"Retrieve a paginated list of all optimization patch revisions for the specified digest. Returns metadata including version, provenance, active status, and timestamps. Use cursor-based pagination for large revision histories.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed or Digest ID","type":"string"},"description":"Feed or Digest ID"},{"name":"limit","in":"query","required":false,"schema":{"default":20,"minimum":1,"maximum":100,"type":"number"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Metadata-only revision list.","content":{"application/json":{"schema":{"type":"object","required":["revisions","nextCursor"],"properties":{"revisions":{"type":"array","items":{"type":"object","required":["id","version","payload","provenance","isActive","generatedAgainstConfigVersion","changedByUserId","activatedAt","deactivatedAt","createdAt"],"properties":{"id":{"type":"number"},"version":{"type":"number"},"payload":{"anyOf":[{"type":"object","patternProperties":{"^(.*)$":{}}},{"type":"null"}]},"provenance":{"type":"string"},"isActive":{"type":"boolean"},"generatedAgainstConfigVersion":{"type":"number"},"changedByUserId":{"anyOf":[{"type":"string"},{"type":"null"}]},"activatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"deactivatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}}}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"404":{"description":"Target entity not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/digests/{id}/optimization/revisions/{revisionId}/rollback":{"post":{"operationId":"rollbackDigestRevision","summary":"Roll back to a specific prior patch revision for a digest.","tags":["Digests","Optimization"],"description":"Reactivate a previously used patch revision for the specified digest, deactivating the currently active revision. Returns 409 if the target revision is already active.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Feed or Digest ID","type":"string"},"description":"Feed or Digest ID"},{"name":"revisionId","in":"path","required":true,"schema":{"description":"Revision ID","type":"string"},"description":"Revision ID"}],"responses":{"200":{"description":"Target revision reactivated.","content":{"application/json":{"schema":{"type":"object","required":["revision","rollbackEvent"],"properties":{"revision":{"type":"object","required":["id","version","payload","provenance","isActive","generatedAgainstConfigVersion","changedByUserId","activatedAt","deactivatedAt","createdAt"],"properties":{"id":{"type":"number"},"version":{"type":"number"},"payload":{"anyOf":[{"type":"object","patternProperties":{"^(.*)$":{}}},{"type":"null"}]},"provenance":{"type":"string"},"isActive":{"type":"boolean"},"generatedAgainstConfigVersion":{"type":"number"},"changedByUserId":{"anyOf":[{"type":"string"},{"type":"null"}]},"activatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"deactivatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}}},"rollbackEvent":{"type":"object","required":["previousActiveRevisionId","rolledBackByUserId"],"properties":{"previousActiveRevisionId":{"anyOf":[{"type":"number"},{"type":"null"}]},"rolledBackByUserId":{"type":"string"}}}}}}}},"404":{"description":"Revision not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Target revision is already active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/org-credentials":{"get":{"operationId":"listOrgCredentialPosture","summary":"List credential posture for singleton types","tags":["Credentials"],"description":"Returns credential summaries and posture (health status) for singleton credential types (x_api, openai_api_key). Admin sees full summaries + posture; members see reduced posture-only data.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Credential summaries with posture assessment","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"description":"Admin: full CredentialSummary[]. Member: reduced posture-only entries.","anyOf":[{"type":"array","items":{"type":"object","required":["id","credentialType","status","version","configured","maskedPreview","metadata","createdAt","createdByUserId","deletedAt"],"properties":{"id":{"type":"string"},"credentialType":{"type":"string"},"status":{"type":"string","enum":["active","rotated","deleted"]},"version":{"type":"number"},"configured":{"type":"boolean"},"maskedPreview":{"anyOf":[{"type":"object","properties":{"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"suffix":{"anyOf":[{"type":"string"},{"type":"null"}]},"validationStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"components":{"anyOf":[{"type":"array","items":{"type":"object","required":["name","maskedValue"],"properties":{"name":{"type":"string"},"maskedValue":{"type":"string"}}}},{"type":"null"}]}}},{"type":"null"}]},"metadata":{"anyOf":[{"type":"object","required":["provenance"],"properties":{"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"provenance":{"type":"string","enum":["customer_managed","platform_managed_migrated"]},"providerAccountHint":{"anyOf":[{"type":"string"},{"type":"null"}]},"validatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"runtimeFailedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"runtimeFailedSourceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"validationMethod":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"createdAt":{"description":"ISO 8601 timestamp","type":"string"},"createdByUserId":{"type":"string"},"deletedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}}}},{"type":"array","items":{"type":"object","required":["credentialType","configured","posture","reason"],"properties":{"credentialType":{"type":"string"},"configured":{"type":"boolean"},"posture":{"type":"string","enum":["platform_managed","customer_managed_healthy","customer_managed_needs_attention"]},"reason":{"anyOf":[{"const":"never_configured","type":"string"},{"const":"deleted_after_setup","type":"string"},{"const":"secret_unreadable","type":"string"},{"const":"provider_rejected","type":"string"},{"const":"validation_pending","type":"string"},{"const":"provider_access_limited","type":"string"},{"type":"null"}]}}}}]},"posture":{"description":"Present for admin only. Omitted for members.","type":"array","items":{"type":"object","required":["credentialType","posture","reason"],"properties":{"credentialType":{"description":"x_api | openai_api_key","type":"string"},"posture":{"type":"string","enum":["platform_managed","customer_managed_healthy","customer_managed_needs_attention"]},"reason":{"anyOf":[{"const":"never_configured","type":"string"},{"const":"deleted_after_setup","type":"string"},{"const":"secret_unreadable","type":"string"},{"const":"provider_rejected","type":"string"},{"const":"validation_pending","type":"string"},{"const":"provider_access_limited","type":"string"},{"type":"null"}]}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"post":{"operationId":"createOrgCredential","summary":"Create or upsert a credential","tags":["Credentials"],"description":"Stores a credential for the organization. Accepts x_api (with mandatory validation), openai_api_key, or http_bearer credential types. For singleton types (x_api, openai_api_key) this upserts the active credential. For http_bearer, creates a new named bearer token.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"additionalProperties":false,"type":"object","required":["credentialType","displayName","secretPayload"],"properties":{"credentialType":{"const":"http_bearer","type":"string"},"displayName":{"minLength":1,"maxLength":100,"type":"string"},"secretPayload":{"additionalProperties":false,"type":"object","required":["bearerToken"],"properties":{"bearerToken":{"minLength":1,"maxLength":4096,"type":"string"}}}}},{"additionalProperties":false,"type":"object","required":["credentialType","secretPayload"],"properties":{"credentialType":{"const":"x_api","type":"string"},"secretPayload":{"additionalProperties":false,"type":"object","required":["consumerKey","consumerSecret","accessToken","accessTokenSecret"],"properties":{"consumerKey":{"minLength":1,"type":"string"},"consumerSecret":{"minLength":1,"type":"string"},"accessToken":{"minLength":1,"type":"string"},"accessTokenSecret":{"minLength":1,"type":"string"}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{}}}}},{"additionalProperties":false,"type":"object","required":["credentialType","secretPayload"],"properties":{"credentialType":{"const":"openai_api_key","type":"string"},"secretPayload":{"additionalProperties":false,"type":"object","required":["apiKey"],"properties":{"apiKey":{"minLength":1,"type":"string"}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{}}}}}],"discriminator":{"propertyName":"credentialType"}}}}},"responses":{"200":{"description":"Created or upserted credential (full summary)","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"anyOf":[{"type":"object","required":["id","credentialType","status","version","configured","maskedPreview","metadata","createdAt","createdByUserId","deletedAt"],"properties":{"id":{"type":"string"},"credentialType":{"type":"string"},"status":{"type":"string","enum":["active","rotated","deleted"]},"version":{"type":"number"},"configured":{"type":"boolean"},"maskedPreview":{"anyOf":[{"type":"object","properties":{"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"suffix":{"anyOf":[{"type":"string"},{"type":"null"}]},"validationStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"components":{"anyOf":[{"type":"array","items":{"type":"object","required":["name","maskedValue"],"properties":{"name":{"type":"string"},"maskedValue":{"type":"string"}}}},{"type":"null"}]}}},{"type":"null"}]},"metadata":{"anyOf":[{"type":"object","required":["provenance"],"properties":{"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"provenance":{"type":"string","enum":["customer_managed","platform_managed_migrated"]},"providerAccountHint":{"anyOf":[{"type":"string"},{"type":"null"}]},"validatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"runtimeFailedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"runtimeFailedSourceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"validationMethod":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"createdAt":{"description":"ISO 8601 timestamp","type":"string"},"createdByUserId":{"type":"string"},"deletedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"object","required":["id","credentialRef","displayName","credentialType","status","version","configured","maskedPreview","linkedSourceCount","metadata","createdAt","createdByUserId"],"properties":{"id":{"type":"string"},"credentialRef":{"type":"string"},"displayName":{"type":"string"},"credentialType":{"const":"http_bearer","type":"string"},"status":{"type":"string","enum":["active","rotated","deleted"]},"version":{"type":"number"},"configured":{"type":"boolean"},"maskedPreview":{"anyOf":[{"type":"object","properties":{"suffix":{"anyOf":[{"type":"string"},{"type":"null"}]},"validationStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"linkedSourceCount":{"type":"number"},"metadata":{"anyOf":[{"type":"object","required":["displayName","provenance","validatedAt","runtimeFailedAt"],"properties":{"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"provenance":{"const":"customer_managed","type":"string"},"validatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"runtimeFailedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"createdAt":{"description":"ISO 8601 timestamp","type":"string"},"createdByUserId":{"type":"string"}}}]},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid request body or missing fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"X API credential validation failed (auth rejected)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"delete":{"operationId":"deleteOrgCredentialByBody","summary":"Delete a credential by type (body-based)","tags":["Credentials"],"description":"Deletes a credential identified by credentialType in the request body. For http_bearer, credentialRef is required to identify the specific bearer credential. For singleton types (x_api, openai_api_key), deletes the active credential.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"additionalProperties":false,"type":"object","required":["credentialType","credentialRef"],"properties":{"credentialType":{"const":"http_bearer","type":"string"},"credentialRef":{"minLength":1,"maxLength":128,"type":"string"}}},{"additionalProperties":false,"type":"object","required":["credentialType"],"properties":{"credentialType":{"type":"string","enum":["x_api","openai_api_key"]}}}]}}}},"responses":{"200":{"description":"Credential deleted","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"anyOf":[{"type":"object","required":["credentialType","credentialRef","deleted"],"properties":{"credentialType":{"const":"http_bearer","type":"string"},"credentialRef":{"type":"string"},"deleted":{"type":"boolean"}}},{"type":"object","required":["credentialType","deleted"],"properties":{"credentialType":{"type":"string"},"deleted":{"type":"boolean"}}}]},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Credential not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/org-credentials/bearer":{"get":{"operationId":"listBearerCredentials","summary":"List bearer credential inventory","tags":["Credentials"],"description":"Returns metadata for all bearer credentials in the organization. Secrets are never included. Requires admin role.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Bearer credential summary list","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","credentialRef","displayName","credentialType","status","version","configured","maskedPreview","linkedSourceCount","metadata","createdAt","createdByUserId"],"properties":{"id":{"type":"string"},"credentialRef":{"type":"string"},"displayName":{"type":"string"},"credentialType":{"const":"http_bearer","type":"string"},"status":{"type":"string","enum":["active","rotated","deleted"]},"version":{"type":"number"},"configured":{"type":"boolean"},"maskedPreview":{"anyOf":[{"type":"object","properties":{"suffix":{"anyOf":[{"type":"string"},{"type":"null"}]},"validationStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"linkedSourceCount":{"type":"number"},"metadata":{"anyOf":[{"type":"object","required":["displayName","provenance","validatedAt","runtimeFailedAt"],"properties":{"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"provenance":{"const":"customer_managed","type":"string"},"validatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"runtimeFailedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"createdAt":{"description":"ISO 8601 timestamp","type":"string"},"createdByUserId":{"type":"string"}}}},"meta":{"type":"object","required":["requestId","total","limit","offset"],"properties":{"requestId":{"format":"uuid","type":"string"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/org-credentials/{ref}":{"post":{"operationId":"rotateOrgCredential","summary":"Rotate a bearer credential","tags":["Credentials"],"description":"Rotates the bearer token for an existing credential identified by ref.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"description":"Credential reference identifier","type":"string"},"description":"Credential reference identifier"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["credentialType","credentialRef","secretPayload"],"properties":{"credentialType":{"const":"http_bearer","type":"string"},"credentialRef":{"minLength":1,"maxLength":128,"type":"string"},"secretPayload":{"additionalProperties":false,"type":"object","required":["bearerToken"],"properties":{"bearerToken":{"minLength":1,"maxLength":4096,"type":"string"}}}}}}}},"responses":{"200":{"description":"Rotated credential summary","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","credentialRef","displayName","credentialType","status","version","configured","maskedPreview","linkedSourceCount","metadata","createdAt","createdByUserId"],"properties":{"id":{"type":"string"},"credentialRef":{"type":"string"},"displayName":{"type":"string"},"credentialType":{"const":"http_bearer","type":"string"},"status":{"type":"string","enum":["active","rotated","deleted"]},"version":{"type":"number"},"configured":{"type":"boolean"},"maskedPreview":{"anyOf":[{"type":"object","properties":{"suffix":{"anyOf":[{"type":"string"},{"type":"null"}]},"validationStatus":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"linkedSourceCount":{"type":"number"},"metadata":{"anyOf":[{"type":"object","required":["displayName","provenance","validatedAt","runtimeFailedAt"],"properties":{"displayName":{"anyOf":[{"type":"string"},{"type":"null"}]},"provenance":{"const":"customer_managed","type":"string"},"validatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"runtimeFailedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"createdAt":{"description":"ISO 8601 timestamp","type":"string"},"createdByUserId":{"type":"string"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Credential not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"delete":{"operationId":"deleteOrgCredential","summary":"Delete a bearer credential by ref","tags":["Credentials"],"description":"Deletes a bearer credential identified by the ref path parameter.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"description":"Credential reference identifier","type":"string"},"description":"Credential reference identifier"}],"responses":{"200":{"description":"Bearer credential deleted","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["credentialType","credentialRef","deleted"],"properties":{"credentialType":{"const":"http_bearer","type":"string"},"credentialRef":{"type":"string"},"deleted":{"type":"boolean"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Credential not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/content-items":{"get":{"operationId":"listContentItems","summary":"List content items with optional filters","tags":["Content Items"],"description":"Returns a paginated list of content items for the authenticated organization. Supports filtering by source ID.","security":[{"bearerAuth":[]}],"parameters":[{"name":"sourceId","in":"query","required":false,"schema":{"description":"Filter content items by source ID.","type":"string"},"description":"Filter content items by source ID."},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"description":"Maximum number of results to return. Default: 50.","type":"integer"},"description":"Maximum number of results to return. Default: 50."},{"name":"offset","in":"query","required":false,"schema":{"minimum":0,"description":"Number of results to skip for pagination. Default: 0.","type":"integer"},"description":"Number of results to skip for pagination. Default: 0."}],"responses":{"200":{"description":"Paginated list of content items","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","source_id","org_id","canonical_url","title","published_at","est_published_at","created_at","acquisition"],"properties":{"id":{"type":"string"},"source_id":{"type":"string"},"org_id":{"type":"string"},"canonical_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"published_at":{"anyOf":[{"description":"ISO 8601 timestamp","type":"string"},{"type":"null"}]},"est_published_at":{"anyOf":[{"description":"Estimated publication date (ISO 8601)","type":"string"},{"type":"null"}]},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"acquisition":{"anyOf":[{"type":"object","required":["sourceType","acquisitionKind","canonical","discoveredVia"],"properties":{"sourceType":{"type":"string"},"acquisitionKind":{"type":"string"},"canonical":{"type":"object","required":["entityType","url","label"],"properties":{"entityType":{"type":"string"},"url":{"type":"string"},"label":{"type":"string"}}},"discoveredVia":{"anyOf":[{"type":"object","required":["entityType","url","label"],"properties":{"entityType":{"type":"string"},"url":{"type":"string"},"label":{"type":"string"}}},{"type":"null"}]}}},{"type":"null"}]}}}},"meta":{"type":"object","required":["requestId","total","limit","offset"],"properties":{"requestId":{"format":"uuid","type":"string"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/content-items/{id}":{"get":{"operationId":"getContentItem","summary":"Get content item details","tags":["Content Items"],"description":"Returns full content item details including text content for the specified content item.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Content item ID","examples":["550e8400-e29b-41d4-a716-446655440000"],"type":"string"},"description":"Content item ID"}],"responses":{"200":{"description":"Content item details","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","source_id","org_id","canonical_url","title","content_text","published_at","est_published_at","created_at","acquisition"],"properties":{"id":{"type":"string"},"source_id":{"type":"string"},"org_id":{"type":"string"},"canonical_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"content_text":{"anyOf":[{"type":"string"},{"type":"null"}]},"published_at":{"anyOf":[{"description":"ISO 8601 timestamp","type":"string"},{"type":"null"}]},"est_published_at":{"anyOf":[{"description":"Estimated publication date (ISO 8601)","type":"string"},{"type":"null"}]},"created_at":{"description":"ISO 8601 timestamp","type":"string"},"acquisition":{"anyOf":[{"type":"object","required":["sourceType","acquisitionKind","canonical","discoveredVia"],"properties":{"sourceType":{"type":"string"},"acquisitionKind":{"type":"string"},"canonical":{"type":"object","required":["entityType","url","label"],"properties":{"entityType":{"type":"string"},"url":{"type":"string"},"label":{"type":"string"}}},"discoveredVia":{"anyOf":[{"type":"object","required":["entityType","url","label"],"properties":{"entityType":{"type":"string"},"url":{"type":"string"},"label":{"type":"string"}}},{"type":"null"}]}}},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Content item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/workspace-reorganizations/plans":{"post":{"operationId":"createWorkspaceReorganizationPlan","summary":"Create a workspace reorganization plan (dry-run)","tags":["Workspace Reorganizations"],"description":"Evaluates a batch of workspace restructuring operations against the current graph state. Returns a plan with actions, blockers, warnings, and impacts. No mutations are performed.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["operations"],"properties":{"operations":{"minItems":1,"description":"One or more workspace restructuring operations to evaluate as a batch.","type":"array","items":{"oneOf":[{"additionalProperties":false,"title":"Move Feed","type":"object","required":["kind","feedId","targetProjectId","sourceProjectLinkPolicy","digestDependencyPolicy"],"properties":{"kind":{"const":"move_feed","type":"string"},"feedId":{"description":"ID of the feed to move","type":"string"},"targetProjectId":{"description":"Destination project ID","type":"string"},"sourceProjectLinkPolicy":{"description":"How to handle source links the target project lacks. `block` rejects if any are missing; `link_missing_to_target` auto-links them.","type":"string","enum":["block","link_missing_to_target"]},"digestDependencyPolicy":{"description":"How to handle digests whose feed_scope references this feed. `block` rejects if any exist; `move_referencing_digests` co-moves them; `remove_from_referencing_digests` rewrites their scope to exclude the feed.","type":"string","enum":["block","move_referencing_digests","remove_from_referencing_digests"]},"movedDigestFeedScopePolicy":{"description":"When co-moving digests, how to handle out-of-project feed references. Required when digestDependencyPolicy is `move_referencing_digests`.","type":"string","enum":["block","trim_to_target_project"]}}},{"additionalProperties":false,"title":"Move Digest","type":"object","required":["kind","digestId","targetProjectId","feedScopePolicy"],"properties":{"kind":{"const":"move_digest","type":"string"},"digestId":{"description":"ID of the digest to move","type":"string"},"targetProjectId":{"description":"Destination project ID","type":"string"},"feedScopePolicy":{"description":"How to handle feed_scope entries outside the target project. `block` rejects if any exist; `trim_to_target_project` rewrites the scope to include only feeds in the target project.","type":"string","enum":["block","trim_to_target_project"]}}},{"additionalProperties":false,"title":"Link Project Source","type":"object","required":["kind","projectId","sourceId"],"properties":{"kind":{"const":"link_project_source","type":"string"},"projectId":{"description":"Project to link the source to","type":"string"},"sourceId":{"description":"Source to link","type":"string"}}},{"additionalProperties":false,"title":"Unlink Project Source","type":"object","required":["kind","projectId","sourceId","feedLinkPolicy"],"properties":{"kind":{"const":"unlink_project_source","type":"string"},"projectId":{"description":"Project to unlink the source from","type":"string"},"sourceId":{"description":"Source to unlink","type":"string"},"feedLinkPolicy":{"description":"How to handle active feeds linked to this source. `block` rejects if any exist; `archive_in_project` archives the feed-source links.","type":"string","enum":["block","archive_in_project"]}}}],"discriminator":{"propertyName":"kind"}}},"reason":{"description":"Optional human-readable reason for the reorganization.","type":"string"}}}}}},"responses":{"200":{"description":"Workspace reorganization plan","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","status","fingerprint","expiresAt","actions","blockers","warnings","impacts"],"properties":{"id":{"description":"Plan ID. Pass this to the apply endpoint.","type":"string"},"status":{"description":"`ready` if all operations can be applied; `blocked` if one or more blockers were detected.","type":"string","enum":["ready","blocked"]},"fingerprint":{"description":"Opaque hash of the graph state at plan time. Required for the apply request.","type":"string"},"expiresAt":{"description":"ISO 8601 timestamp after which the plan can no longer be applied.","type":"string"},"reason":{"description":"Caller-supplied reason, echoed back.","type":"string"},"actions":{"description":"Ordered list of mutations the plan will perform.","type":"array","items":{"type":"object","required":["actionId","origin","operationIndex","kind","entityIds","summary"],"properties":{"actionId":{"description":"Unique identifier for this action within the plan.","type":"string"},"origin":{"description":"`explicit` if directly requested by an operation; `synthesized` if generated to satisfy a dependency.","type":"string","enum":["explicit","synthesized"]},"operationIndex":{"description":"Zero-based index of the originating operation in the request.","type":"integer"},"kind":{"description":"The mutation type this action will perform.","type":"string","enum":["move_feed_row","move_digest_row","link_project_source","archive_project_source","archive_feed_source","rewrite_digest_scope"]},"entityIds":{"description":"IDs of the entities affected by this action.","type":"array","items":{"type":"string"}},"summary":{"description":"Human-readable description of what this action does.","type":"string"}}}},"blockers":{"description":"Issues that prevent the plan from being applied. Empty when status is `ready`.","type":"array","items":{"type":"object","required":["code","message","operationIndex"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"operationIndex":{"type":"integer"},"entityIds":{"type":"array","items":{"type":"string"}}}}},"warnings":{"description":"Non-blocking observations about side-effects.","type":"array","items":{"type":"object","required":["code","message","operationIndex"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"operationIndex":{"type":"integer"},"entityIds":{"type":"array","items":{"type":"string"}}}}},"impacts":{"type":"object","required":["movedFeedIds","movedDigestIds","linkedProjectSources","archivedProjectSources","archivedFeedSources","digestScopeRewrites","implicitDigestScopeImpacts"],"properties":{"movedFeedIds":{"type":"array","items":{"type":"string"}},"movedDigestIds":{"type":"array","items":{"type":"string"}},"linkedProjectSources":{"type":"array","items":{"type":"object","required":["projectId","sourceId"],"properties":{"projectId":{"type":"string"},"sourceId":{"type":"string"}}}},"archivedProjectSources":{"type":"array","items":{"type":"object","required":["projectId","sourceId"],"properties":{"projectId":{"type":"string"},"sourceId":{"type":"string"}}}},"archivedFeedSources":{"type":"array","items":{"type":"object","required":["feedId","sourceId"],"properties":{"feedId":{"type":"string"},"sourceId":{"type":"string"}}}},"digestScopeRewrites":{"type":"array","items":{"type":"object","required":["digestId","beforeFeedScope","afterFeedScope"],"properties":{"digestId":{"type":"string"},"beforeFeedScope":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"afterFeedScope":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}}}},"implicitDigestScopeImpacts":{"type":"array","items":{"type":"object","required":["digestId","sourceProjectId","removedFeedIds","addedFeedIds"],"properties":{"digestId":{"type":"string"},"sourceProjectId":{"type":"string"},"targetProjectId":{"type":"string"},"removedFeedIds":{"type":"array","items":{"type":"string"}},"addedFeedIds":{"type":"array","items":{"type":"string"}}}}}}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Not org:admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/workspace-reorganizations/plans/{planId}/apply":{"post":{"operationId":"applyWorkspaceReorganizationPlan","summary":"Apply a workspace reorganization plan","tags":["Workspace Reorganizations"],"description":"Executes a previously created plan atomically. Includes stale-plan detection via fingerprint recheck and idempotent replay on (planId, idempotencyKey).","security":[{"bearerAuth":[]}],"parameters":[{"name":"planId","in":"path","required":true,"schema":{"description":"Workspace reorganization plan ID","type":"string"},"description":"Workspace reorganization plan ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"type":"object","required":["fingerprint","idempotencyKey"],"properties":{"fingerprint":{"description":"Fingerprint returned by the plan endpoint. Apply fails with 409 if the graph has changed since the plan was created.","type":"string"},"idempotencyKey":{"minLength":1,"description":"Caller-supplied idempotency key. Duplicate applies with the same key replay the prior result.","type":"string"}}}}}},"responses":{"200":{"description":"Apply result with actions and impacts","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["runId","planId","status","appliedAt","actions","impacts"],"properties":{"runId":{"description":"Unique audit run identifier.","type":"string"},"planId":{"description":"Plan that was applied.","type":"string"},"status":{"const":"applied","type":"string"},"appliedAt":{"description":"ISO 8601 timestamp of when the plan was applied.","type":"string"},"actions":{"description":"Actions that were executed.","type":"array","items":{"type":"object","required":["actionId","origin","operationIndex","kind","entityIds","summary"],"properties":{"actionId":{"description":"Unique identifier for this action within the plan.","type":"string"},"origin":{"description":"`explicit` if directly requested by an operation; `synthesized` if generated to satisfy a dependency.","type":"string","enum":["explicit","synthesized"]},"operationIndex":{"description":"Zero-based index of the originating operation in the request.","type":"integer"},"kind":{"description":"The mutation type this action will perform.","type":"string","enum":["move_feed_row","move_digest_row","link_project_source","archive_project_source","archive_feed_source","rewrite_digest_scope"]},"entityIds":{"description":"IDs of the entities affected by this action.","type":"array","items":{"type":"string"}},"summary":{"description":"Human-readable description of what this action does.","type":"string"}}}},"impacts":{"type":"object","required":["movedFeedIds","movedDigestIds","linkedProjectSources","archivedProjectSources","archivedFeedSources","digestScopeRewrites","implicitDigestScopeImpacts"],"properties":{"movedFeedIds":{"type":"array","items":{"type":"string"}},"movedDigestIds":{"type":"array","items":{"type":"string"}},"linkedProjectSources":{"type":"array","items":{"type":"object","required":["projectId","sourceId"],"properties":{"projectId":{"type":"string"},"sourceId":{"type":"string"}}}},"archivedProjectSources":{"type":"array","items":{"type":"object","required":["projectId","sourceId"],"properties":{"projectId":{"type":"string"},"sourceId":{"type":"string"}}}},"archivedFeedSources":{"type":"array","items":{"type":"object","required":["feedId","sourceId"],"properties":{"feedId":{"type":"string"},"sourceId":{"type":"string"}}}},"digestScopeRewrites":{"type":"array","items":{"type":"object","required":["digestId","beforeFeedScope","afterFeedScope"],"properties":{"digestId":{"type":"string"},"beforeFeedScope":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"afterFeedScope":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}}}},"implicitDigestScopeImpacts":{"type":"array","items":{"type":"object","required":["digestId","sourceProjectId","removedFeedIds","addedFeedIds"],"properties":{"digestId":{"type":"string"},"sourceProjectId":{"type":"string"},"targetProjectId":{"type":"string"},"removedFeedIds":{"type":"array","items":{"type":"string"}},"addedFeedIds":{"type":"array","items":{"type":"string"}}}}}}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"400":{"description":"Invalid request, plan expired, or plan blocked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Not org:admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Plan not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Stale plan or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/source-catalog/search":{"get":{"operationId":"searchCatalog","summary":"Search the source catalog","tags":["Source Catalog"],"description":"Search for available source templates in the catalog. Supports text search, filtering by source type and category, and pagination. Returns matching catalog entries with facet counts for source types and categories.","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"maxLength":500,"description":"Free-text search query","type":"string"},"description":"Free-text search query"},{"name":"platform","in":"query","required":false,"schema":{"description":"Platform filter (comma-separated for multiple)","type":"string"},"description":"Platform filter (comma-separated for multiple)"},{"name":"sourceType","in":"query","required":false,"schema":{"description":"Source type filter (comma-separated for multiple)","type":"string"},"description":"Source type filter (comma-separated for multiple)"},{"name":"topic","in":"query","required":false,"schema":{"description":"Topic filter (comma-separated for multiple)","type":"string"},"description":"Topic filter (comma-separated for multiple)"},{"name":"domain","in":"query","required":false,"schema":{"description":"Domain filter (comma-separated for multiple)","type":"string"},"description":"Domain filter (comma-separated for multiple)"},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"description":"Page size (1-100, default 20)","type":"integer"},"description":"Page size (1-100, default 20)"},{"name":"cursor","in":"query","required":false,"schema":{"description":"Opaque pagination cursor","type":"string"},"description":"Opaque pagination cursor"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["relevance","name"]}}],"responses":{"200":{"description":"Search results with facets and pagination","content":{"application/json":{"schema":{"type":"object","required":["query","page","facets","results"],"properties":{"query":{"type":"object","required":["q","filters","sort"],"properties":{"q":{"anyOf":[{"type":"string"},{"type":"null"}]},"filters":{"type":"object","required":["platform","sourceType","topic","domain"],"properties":{"platform":{"type":"array","items":{"type":"string"}},"sourceType":{"type":"array","items":{"type":"string"}},"topic":{"type":"array","items":{"type":"string"}},"domain":{"type":"array","items":{"type":"string"}}}},"sort":{"type":"string","enum":["relevance","name"]}}},"page":{"type":"object","required":["limit","nextCursor"],"properties":{"limit":{"type":"integer"},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}}},"facets":{"type":"object","required":["platforms","sourceTypes","topics"],"properties":{"platforms":{"type":"array","items":{"type":"object","required":["value","count"],"properties":{"value":{"type":"string"},"count":{"type":"integer"}}}},"sourceTypes":{"type":"array","items":{"type":"object","required":["value","count"],"properties":{"value":{"type":"string"},"count":{"type":"integer"}}}},"topics":{"type":"array","items":{"type":"object","required":["value","count"],"properties":{"value":{"type":"string"},"count":{"type":"integer"}}}}}},"results":{"type":"array","items":{"type":"object","required":["id","name","summary","sourceType","platform","domain","homepageUrl","topics"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"sourceType":{"description":"Cortex source type taxonomy","type":"string","enum":["rss","web","x_profile","x_list","x_search","api_endpoint"]},"platform":{"anyOf":[{"type":"string"},{"type":"null"}]},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"homepageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"topics":{"type":"array","items":{"type":"string"}}}}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/source-catalog/entries/{id}":{"get":{"operationId":"getCatalogEntry","summary":"Get catalog entry detail","tags":["Source Catalog"],"description":"Retrieve detailed information about a specific source catalog entry, including its source draft configuration and metadata. Only returns entries with public visibility. Returns 404 if the entry does not exist or is not publicly visible.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$","description":"Catalog entry UUID","type":"string"},"description":"Catalog entry UUID"}],"responses":{"200":{"description":"Catalog entry with sanitized public source draft","content":{"application/json":{"schema":{"type":"object","required":["entry"],"properties":{"entry":{"type":"object","required":["id","name","summary","aliases","sourceType","platform","domain","homepageUrl","topics","publicSourceDraft","setupMetadata"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"sourceType":{"description":"Cortex source type taxonomy","type":"string","enum":["rss","web","x_profile","x_list","x_search","api_endpoint"]},"platform":{"anyOf":[{"type":"string"},{"type":"null"}]},"domain":{"anyOf":[{"type":"string"},{"type":"null"}]},"homepageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"topics":{"type":"array","items":{"type":"string"}},"publicSourceDraft":{"type":"object","required":["sourceType","name","url","connectorConfig"],"properties":{"sourceType":{"description":"Cortex source type taxonomy","type":"string","enum":["rss","web","x_profile","x_list","x_search","api_endpoint"]},"name":{"type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"connectorConfig":{"anyOf":[{"type":"object","patternProperties":{"^(.*)$":{}}},{"type":"null"}]}}},"setupMetadata":{"type":"object","patternProperties":{"^(.*)$":{}}}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Entry not found or not public","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/examples":{"get":{"operationId":"listExamples","summary":"List available examples","tags":["Examples"],"description":"Returns a list of available example setups with compact discovery metadata.","security":[{"bearerAuth":[]}],"parameters":[{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["starter","source","feed","digest"]}}],"responses":{"200":{"description":"List of examples","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","kind","title","summary","sourceType","guideId","guideType","guidePath"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["starter","source","feed","digest"]},"title":{"type":"string"},"summary":{"type":"string"},"sourceType":{"anyOf":[{"type":"string"},{"type":"null"}]},"guideId":{"anyOf":[{"type":"string"},{"type":"null"}]},"guideType":{"anyOf":[{"type":"string","enum":["example","source-type"]},{"type":"null"}]},"guidePath":{"anyOf":[{"type":"string"},{"type":"null"}]}}}},"meta":{"type":"object","required":["requestId","total","limit","offset"],"properties":{"requestId":{"format":"uuid","type":"string"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/examples/{id}":{"get":{"operationId":"getExample","summary":"Get example detail","tags":["Examples"],"description":"Retrieves full example detail including kind-appropriate composition data and linked guide metadata.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Example identifier","type":"string"},"description":"Example identifier"}],"responses":{"200":{"description":"Example detail","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","kind","title","summary","prerequisites","composition","guide"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["starter","source","feed","digest"]},"title":{"type":"string"},"summary":{"type":"string"},"prerequisites":{"type":"array","items":{"type":"object","required":["id","label","required"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"required":{"type":"boolean"},"notes":{"type":"string"}}}},"composition":{"oneOf":[{"type":"object","required":["kind","project","sources","feeds","digests"],"properties":{"kind":{"const":"starter","type":"string"},"project":{"type":"object","required":["alias","body"],"properties":{"alias":{"type":"string"},"body":{"type":"object","required":["name","objective"],"properties":{"name":{"type":"string"},"objective":{"type":"string"}}}}},"sources":{"type":"array","items":{"type":"object","required":["alias","body"],"properties":{"alias":{"type":"string"},"body":{"additionalProperties":true,"type":"object","required":["name","sourceType"],"properties":{"name":{"type":"string"},"sourceType":{"type":"string"},"url":{"type":"string"},"connectorConfig":{"anyOf":[{"type":"object","required":["selectors"],"properties":{"selectors":{"description":"CSS selectors for extracting items from the listing page. item and link are required; title, date, and dateAttribute are optional listing-level metadata selectors.","type":"object","required":["item","link"],"properties":{"item":{"minLength":1,"description":"CSS selector for the repeating container element on the listing page. Each match becomes one content item.","examples":["article.blog-card","div.post-entry","li.feed-item"],"type":"string"},"link":{"minLength":1,"description":"CSS selector for the link element within each item container. Use \":self\" if the item element itself is an <a> tag.","examples":["a","a.post-link",":self"],"type":"string"},"title":{"minLength":1,"description":"CSS selector for the title element within each listing item. Extracts the title from the listing page rather than the linked article.","examples":["h3","h2.post-title"],"type":"string"},"date":{"minLength":1,"description":"CSS selector for the date element within each listing item.","examples":["time","span.date","h3 + div"],"type":"string"},"dateAttribute":{"minLength":1,"description":"HTML attribute on the listing-level date element that contains the date value. Omit to read the element text content.","examples":["datetime","content"],"type":"string"}}},"pageSelectors":{"description":"Optional selectors applied to each linked article page to extract structured metadata. If omitted, only listing-page data is used.","type":"object","properties":{"title":{"minLength":1,"description":"CSS selector for the article title on the linked article page.","examples":["h1","h1.article-title"],"type":"string"},"date":{"minLength":1,"description":"CSS selector for the publish-date element on the linked article page.","examples":["time","span.date"],"type":"string"},"dateAttribute":{"minLength":1,"description":"HTML attribute on the date element that contains the date value. Omit to read the element text content.","examples":["datetime"],"type":"string"}}},"linkTransform":{"description":"Optional regex transform applied to extracted URLs before they become canonical URLs. Useful for converting view-URLs to raw/API URLs.","type":"object","required":["match","replace"],"properties":{"match":{"minLength":1,"description":"Regex pattern applied to each resolved listing URL before canonicalization.","examples":["github\\.com/([^/]+)/([^/]+)/blob/([^/]+)/(.*)"],"type":"string"},"replace":{"minLength":1,"description":"Regex replacement string for rewritten listing URLs.","examples":["raw.githubusercontent.com/$1/$2/refs/heads/$3/$4"],"type":"string"}}},"waitFor":{"type":"string"},"jsCode":{"type":"string"},"delaySeconds":{"type":"number"},"userAgent":{"type":"string"}}},{"type":"object","required":["username"],"properties":{"username":{"type":"string"},"max_results":{"minimum":1,"maximum":200,"description":"Maximum tweets to fetch per poll cycle. Default: 200.","type":"integer"},"min_likes":{"minimum":0,"description":"Skip tweets with fewer likes than this threshold. Default: 0 (no filter).","type":"integer"},"min_retweets":{"minimum":0,"description":"Skip tweets with fewer retweets than this threshold. Default: 0 (no filter).","type":"integer"},"min_replies":{"minimum":0,"description":"Skip tweets with fewer replies than this threshold. Default: 0 (no filter).","type":"integer"},"exclude_retweets":{"description":"Exclude retweets from the results. Default: false.","type":"boolean"},"exclude_replies":{"description":"Exclude replies from the results. Default: false.","type":"boolean"}}},{"type":"object","required":["list_id"],"properties":{"list_id":{"type":"string"},"max_results":{"minimum":1,"maximum":200,"description":"Maximum tweets to fetch per poll cycle. Default: 200.","type":"integer"},"min_likes":{"minimum":0,"description":"Skip tweets with fewer likes than this threshold. Default: 0 (no filter).","type":"integer"},"min_retweets":{"minimum":0,"description":"Skip tweets with fewer retweets than this threshold. Default: 0 (no filter).","type":"integer"},"min_replies":{"minimum":0,"description":"Skip tweets with fewer replies than this threshold. Default: 0 (no filter).","type":"integer"},"exclude_retweets":{"description":"Exclude retweets from the results. Default: false.","type":"boolean"},"exclude_replies":{"description":"Exclude replies from the results. Default: false.","type":"boolean"}}},{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"sort_order":{"type":"string","enum":["relevancy","recency"]},"max_results":{"minimum":1,"maximum":200,"description":"Maximum tweets to fetch per poll cycle. Default: 200.","type":"integer"},"min_likes":{"minimum":0,"description":"Skip tweets with fewer likes than this threshold. Default: 0 (no filter).","type":"integer"},"min_retweets":{"minimum":0,"description":"Skip tweets with fewer retweets than this threshold. Default: 0 (no filter).","type":"integer"},"min_replies":{"minimum":0,"description":"Skip tweets with fewer replies than this threshold. Default: 0 (no filter).","type":"integer"},"exclude_retweets":{"description":"Exclude retweets from the results. Default: false.","type":"boolean"},"exclude_replies":{"description":"Exclude replies from the results. Default: false.","type":"boolean"}}},{"type":"object","required":["request","extract"],"properties":{"request":{"additionalProperties":false,"type":"object","required":["url"],"properties":{"url":{"minLength":1,"description":"HTTPS URL of the JSON API endpoint.","type":"string"},"auth":{"additionalProperties":false,"type":"object","required":["mode","credentialRef"],"properties":{"mode":{"const":"bearer_credential","type":"string"},"credentialRef":{"minLength":1,"maxLength":128,"type":"string"}}},"headers":{"maxItems":5,"type":"array","items":{"additionalProperties":false,"type":"object","required":["name","value"],"properties":{"name":{"minLength":1,"maxLength":64,"type":"string"},"value":{"minLength":1,"maxLength":256,"type":"string"}}}}}},"extract":{"additionalProperties":false,"type":"object","required":["itemsPath","urlPath","textPath"],"properties":{"itemsPath":{"minLength":1,"description":"JSONPath expression selecting the array of items in the API response.","examples":["$.items[*]","$.data.articles[*]","$[*]"],"type":"string"},"urlPath":{"minLength":1,"description":"JSONPath expression selecting each item's canonical URL (relative to each item).","examples":["$.url","$.link","$.canonical_url"],"type":"string"},"textPath":{"minLength":1,"description":"JSONPath expression selecting each item's main text content (relative to each item).","examples":["$.body","$.content","$.description"],"type":"string"},"titlePath":{"minLength":1,"description":"JSONPath expression selecting each item's title (relative to each item). Optional.","examples":["$.title","$.headline"],"type":"string"},"publishedAtPath":{"minLength":1,"description":"JSONPath expression selecting each item's publish timestamp (relative to each item). Optional; parsed as ISO 8601.","examples":["$.published_at","$.date","$.created"],"type":"string"}}}}}]}}}}}},"feeds":{"type":"array","items":{"type":"object","required":["alias","body"],"properties":{"alias":{"type":"string"},"sourceAliases":{"type":"array","items":{"type":"string"}},"body":{"additionalProperties":true,"type":"object","required":["name","objective"],"properties":{"name":{"type":"string"},"objective":{"type":"string"}}}}}},"digests":{"type":"array","items":{"type":"object","required":["alias","body"],"properties":{"alias":{"type":"string"},"feedAliases":{"type":"array","items":{"type":"string"}},"body":{"additionalProperties":true,"type":"object","required":["name","config"],"properties":{"name":{"type":"string"},"config":{"type":"object","patternProperties":{"^(.*)$":{}}}}}}}}}},{"type":"object","required":["kind","source"],"properties":{"kind":{"const":"source","type":"string"},"source":{"type":"object","required":["alias","body"],"properties":{"alias":{"type":"string"},"body":{"additionalProperties":true,"type":"object","required":["name","sourceType"],"properties":{"name":{"type":"string"},"sourceType":{"type":"string"},"url":{"type":"string"},"connectorConfig":{"anyOf":[{"type":"object","required":["selectors"],"properties":{"selectors":{"description":"CSS selectors for extracting items from the listing page. item and link are required; title, date, and dateAttribute are optional listing-level metadata selectors.","type":"object","required":["item","link"],"properties":{"item":{"minLength":1,"description":"CSS selector for the repeating container element on the listing page. Each match becomes one content item.","examples":["article.blog-card","div.post-entry","li.feed-item"],"type":"string"},"link":{"minLength":1,"description":"CSS selector for the link element within each item container. Use \":self\" if the item element itself is an <a> tag.","examples":["a","a.post-link",":self"],"type":"string"},"title":{"minLength":1,"description":"CSS selector for the title element within each listing item. Extracts the title from the listing page rather than the linked article.","examples":["h3","h2.post-title"],"type":"string"},"date":{"minLength":1,"description":"CSS selector for the date element within each listing item.","examples":["time","span.date","h3 + div"],"type":"string"},"dateAttribute":{"minLength":1,"description":"HTML attribute on the listing-level date element that contains the date value. Omit to read the element text content.","examples":["datetime","content"],"type":"string"}}},"pageSelectors":{"description":"Optional selectors applied to each linked article page to extract structured metadata. If omitted, only listing-page data is used.","type":"object","properties":{"title":{"minLength":1,"description":"CSS selector for the article title on the linked article page.","examples":["h1","h1.article-title"],"type":"string"},"date":{"minLength":1,"description":"CSS selector for the publish-date element on the linked article page.","examples":["time","span.date"],"type":"string"},"dateAttribute":{"minLength":1,"description":"HTML attribute on the date element that contains the date value. Omit to read the element text content.","examples":["datetime"],"type":"string"}}},"linkTransform":{"description":"Optional regex transform applied to extracted URLs before they become canonical URLs. Useful for converting view-URLs to raw/API URLs.","type":"object","required":["match","replace"],"properties":{"match":{"minLength":1,"description":"Regex pattern applied to each resolved listing URL before canonicalization.","examples":["github\\.com/([^/]+)/([^/]+)/blob/([^/]+)/(.*)"],"type":"string"},"replace":{"minLength":1,"description":"Regex replacement string for rewritten listing URLs.","examples":["raw.githubusercontent.com/$1/$2/refs/heads/$3/$4"],"type":"string"}}},"waitFor":{"type":"string"},"jsCode":{"type":"string"},"delaySeconds":{"type":"number"},"userAgent":{"type":"string"}}},{"type":"object","required":["username"],"properties":{"username":{"type":"string"},"max_results":{"minimum":1,"maximum":200,"description":"Maximum tweets to fetch per poll cycle. Default: 200.","type":"integer"},"min_likes":{"minimum":0,"description":"Skip tweets with fewer likes than this threshold. Default: 0 (no filter).","type":"integer"},"min_retweets":{"minimum":0,"description":"Skip tweets with fewer retweets than this threshold. Default: 0 (no filter).","type":"integer"},"min_replies":{"minimum":0,"description":"Skip tweets with fewer replies than this threshold. Default: 0 (no filter).","type":"integer"},"exclude_retweets":{"description":"Exclude retweets from the results. Default: false.","type":"boolean"},"exclude_replies":{"description":"Exclude replies from the results. Default: false.","type":"boolean"}}},{"type":"object","required":["list_id"],"properties":{"list_id":{"type":"string"},"max_results":{"minimum":1,"maximum":200,"description":"Maximum tweets to fetch per poll cycle. Default: 200.","type":"integer"},"min_likes":{"minimum":0,"description":"Skip tweets with fewer likes than this threshold. Default: 0 (no filter).","type":"integer"},"min_retweets":{"minimum":0,"description":"Skip tweets with fewer retweets than this threshold. Default: 0 (no filter).","type":"integer"},"min_replies":{"minimum":0,"description":"Skip tweets with fewer replies than this threshold. Default: 0 (no filter).","type":"integer"},"exclude_retweets":{"description":"Exclude retweets from the results. Default: false.","type":"boolean"},"exclude_replies":{"description":"Exclude replies from the results. Default: false.","type":"boolean"}}},{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"sort_order":{"type":"string","enum":["relevancy","recency"]},"max_results":{"minimum":1,"maximum":200,"description":"Maximum tweets to fetch per poll cycle. Default: 200.","type":"integer"},"min_likes":{"minimum":0,"description":"Skip tweets with fewer likes than this threshold. Default: 0 (no filter).","type":"integer"},"min_retweets":{"minimum":0,"description":"Skip tweets with fewer retweets than this threshold. Default: 0 (no filter).","type":"integer"},"min_replies":{"minimum":0,"description":"Skip tweets with fewer replies than this threshold. Default: 0 (no filter).","type":"integer"},"exclude_retweets":{"description":"Exclude retweets from the results. Default: false.","type":"boolean"},"exclude_replies":{"description":"Exclude replies from the results. Default: false.","type":"boolean"}}},{"type":"object","required":["request","extract"],"properties":{"request":{"additionalProperties":false,"type":"object","required":["url"],"properties":{"url":{"minLength":1,"description":"HTTPS URL of the JSON API endpoint.","type":"string"},"auth":{"additionalProperties":false,"type":"object","required":["mode","credentialRef"],"properties":{"mode":{"const":"bearer_credential","type":"string"},"credentialRef":{"minLength":1,"maxLength":128,"type":"string"}}},"headers":{"maxItems":5,"type":"array","items":{"additionalProperties":false,"type":"object","required":["name","value"],"properties":{"name":{"minLength":1,"maxLength":64,"type":"string"},"value":{"minLength":1,"maxLength":256,"type":"string"}}}}}},"extract":{"additionalProperties":false,"type":"object","required":["itemsPath","urlPath","textPath"],"properties":{"itemsPath":{"minLength":1,"description":"JSONPath expression selecting the array of items in the API response.","examples":["$.items[*]","$.data.articles[*]","$[*]"],"type":"string"},"urlPath":{"minLength":1,"description":"JSONPath expression selecting each item's canonical URL (relative to each item).","examples":["$.url","$.link","$.canonical_url"],"type":"string"},"textPath":{"minLength":1,"description":"JSONPath expression selecting each item's main text content (relative to each item).","examples":["$.body","$.content","$.description"],"type":"string"},"titlePath":{"minLength":1,"description":"JSONPath expression selecting each item's title (relative to each item). Optional.","examples":["$.title","$.headline"],"type":"string"},"publishedAtPath":{"minLength":1,"description":"JSONPath expression selecting each item's publish timestamp (relative to each item). Optional; parsed as ISO 8601.","examples":["$.published_at","$.date","$.created"],"type":"string"}}}}}]}}}}}}},{"type":"object","required":["kind","feed"],"properties":{"kind":{"const":"feed","type":"string"},"feed":{"type":"object","required":["alias","body"],"properties":{"alias":{"type":"string"},"sourceAliases":{"type":"array","items":{"type":"string"}},"body":{"additionalProperties":true,"type":"object","required":["name","objective"],"properties":{"name":{"type":"string"},"objective":{"type":"string"}}}}}}},{"type":"object","required":["kind","digest"],"properties":{"kind":{"const":"digest","type":"string"},"digest":{"type":"object","required":["alias","body"],"properties":{"alias":{"type":"string"},"feedAliases":{"type":"array","items":{"type":"string"}},"body":{"additionalProperties":true,"type":"object","required":["name","config"],"properties":{"name":{"type":"string"},"config":{"type":"object","patternProperties":{"^(.*)$":{}}}}}}}}}],"discriminator":{"propertyName":"kind"}},"notes":{"type":"array","items":{"type":"object","required":["label","text"],"properties":{"label":{"type":"string"},"text":{"type":"string"}}}},"guide":{"anyOf":[{"type":"object","required":["id","type","path"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["example","source-type"]},"path":{"type":"string"}}},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Example not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/docs/search":{"get":{"operationId":"searchDocs","summary":"Search documentation","tags":["Documentation"],"description":"Search normalized product documentation by free-text query. Returns matching documents with optional chunk-level hit IDs.","security":[{"bearerAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"minLength":1,"description":"Free-text search query","type":"string"},"description":"Free-text search query"},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["guide","api-reference"]}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":50,"description":"Max results (default: 10)","type":"integer"},"description":"Max results (default: 10)"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","kind","title","path","summary"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["guide","api-reference"]},"title":{"type":"string"},"path":{"anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"matchingChunkIds":{"type":"array","items":{"type":"string"}}}}},"meta":{"type":"object","required":["requestId","total","limit","offset"],"properties":{"requestId":{"format":"uuid","type":"string"},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Missing query or invalid limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/docs/{id}":{"get":{"operationId":"getDoc","summary":"Get document detail","tags":["Documentation"],"description":"Retrieves a full normalized document with chunked text content.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Document identifier","type":"string"},"description":"Document identifier"}],"responses":{"200":{"description":"Document detail","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","kind","title","path","summary","chunks"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["guide","api-reference"]},"title":{"type":"string"},"path":{"anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"chunks":{"type":"array","items":{"type":"object","required":["id","heading","text"],"properties":{"id":{"type":"string"},"heading":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"type":"string"}}}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}}},"components":{"schemas":{"ApiErrorEnvelope":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"format":"uuid","type":"string"}}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}