{"openapi":"3.1.0","info":{"title":"Bri Authorized API Contract","version":"2026-06-15","summary":"Authenticated contract for Subscription-backed Newspaper and Podcast Briefings.","description":"Bri lets authorized agents and users manage RSS or Atom Subscriptions and create source-backed Newspaper and Podcast Briefings. This contract is public for discovery and planning, but access requires Bri-issued Skill Session or connector credentials.","contact":{"email":"hi@bri.so","url":"https://bri.so/contact"}},"servers":[{"url":"https://bri.so","description":"Bri Worker gateway"}],"externalDocs":{"description":"Bri agent reference","url":"https://bri.so/llms-full.txt"},"tags":[{"name":"Auth","description":"Skill Session and agent authentication entrypoints."},{"name":"Subscriptions","description":"Manage RSS and Atom Subscriptions."},{"name":"Feed Items","description":"List and read Feed Items visible through Subscriptions."},{"name":"Briefings","description":"Create and inspect Newspaper and Podcast Briefings."},{"name":"Settings","description":"Read and update small user preferences."}],"paths":{"/api/v1/auth/skill":{"get":{"operationId":"startSkillAuth","tags":["Auth"],"summary":"Start Bri Skill authentication with PKCE and redirect to the authorize flow.","security":[],"parameters":[{"name":"code_challenge","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"PKCE code challenge generated by the Skill client."},{"name":"state","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Opaque client state returned after authorization."}],"responses":{"302":{"description":"Redirects the browser to the Bri Skill authorize URL.","headers":{"Location":{"description":"Bri Skill authorize URL.","schema":{"type":"string","format":"uri"}}}},"400":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/subscriptions/list":{"post":{"operationId":"listSubscriptions","tags":["Subscriptions"],"summary":"List active Subscriptions for the authenticated user.","security":[{"skillSession":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"cursor":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50},"query":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSubscriptionsResponse"}}}},"401":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/subscriptions/create":{"post":{"operationId":"createSubscription","tags":["Subscriptions"],"summary":"Create or reactivate one RSS or Atom Subscription.","security":[{"skillSession":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":["feed_url"],"properties":{"feed_url":{"type":"string","format":"uri"},"source_id":{"type":"string"}}}}}},"responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriptionResponse"}}}},"400":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/subscriptions/delete":{"post":{"operationId":"deleteSubscription","tags":["Subscriptions"],"summary":"Soft-delete one Subscription owned by the authenticated user.","security":[{"skillSession":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":["subscription_id"],"properties":{"subscription_id":{"type":"string"}}}}}},"responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"type":"object","required":["deleted"],"properties":{"deleted":{"type":"boolean"}}}}}},"401":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/items/list":{"post":{"operationId":"listFeedItems","tags":["Feed Items"],"summary":"List Feed Items visible through the authenticated user's Subscriptions.","security":[{"skillSession":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"cursor":{"type":"string"},"ids":{"type":"array","items":{"type":"string"}},"keyword":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20},"published_after":{"type":"integer"},"published_before":{"type":"integer"},"search_content":{"type":"boolean","default":false},"subscription_id":{"type":"string"}}}}}},"responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListFeedItemsResponse"}}}},"401":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/items/get":{"post":{"operationId":"getFeedItem","tags":["Feed Items"],"summary":"Read one Feed Item through a Skill Session.","security":[{"skillSession":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":["item_id"],"properties":{"cursor":{"type":"string"},"include_raw":{"type":"boolean","default":false},"item_id":{"type":"string"},"max_chars":{"type":"integer","minimum":1,"maximum":20000,"default":12000}}}}}},"responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetFeedItemResponse"}}}},"401":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/artifact-compositions":{"post":{"operationId":"createBriefing","tags":["Briefings"],"summary":"Request a source-backed Newspaper or Podcast Briefing.","security":[{"skillSession":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":["artifact_type","user_request"],"properties":{"artifact_type":{"type":"string","enum":["briefing_page","audio_brief"]},"user_request":{"type":"string","maxLength":4000},"timezone":{"type":"string","description":"IANA timezone name."},"scope":{"type":"object","additionalProperties":true},"refs":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactCompositionResponse"}}}},"202":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactCompositionResponse"}}}},"401":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/artifacts/list":{"post":{"operationId":"listBriefings","tags":["Briefings"],"summary":"List recent Briefings for the authenticated user.","security":[{"skillSession":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"cursor":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":25,"default":10},"type":{"type":"string","enum":["briefing_page","audio_brief"]}}}}}},"responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListArtifactsResponse"}}}},"401":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/artifacts/get":{"post":{"operationId":"getBriefing","tags":["Briefings"],"summary":"Get status and public links for one Briefing.","security":[{"skillSession":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":["id"],"additionalProperties":false,"properties":{"id":{"type":"string"}}}}}},"responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactResponse"}}}},"401":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/settings/get":{"post":{"operationId":"getSettings","tags":["Settings"],"summary":"Read the authenticated user's small Bri preferences.","security":[{"skillSession":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsResponse"}}}},"401":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/settings/update":{"post":{"operationId":"updateSettings","tags":["Settings"],"summary":"Update small Bri preferences such as language or timezone.","security":[{"skillSession":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"profile":{"type":"object","additionalProperties":false,"properties":{"language":{"type":"string"},"timezone":{"type":"string"}}}}}}}},"responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsResponse"}}}},"400":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Structured JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"skillSession":{"type":"http","scheme":"bearer","bearerFormat":"Bri Skill Session","description":"Skill Session bearer token from the Bri Auth Entry or pair flow."}},"schemas":{"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable recovery hint."}}},"Subscription":{"type":"object","required":["id","type","title","feed_url","created_at","updated_at"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["rss"]},"title":{"type":"string"},"feed_url":{"type":"string","format":"uri"},"site_url":{"type":["string","null"],"format":"uri"},"last_success_at":{"type":["integer","null"]},"last_error":{"type":["string","null"]},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"ListSubscriptionsResponse":{"type":"object","required":["subscriptions"],"properties":{"next_cursor":{"type":["string","null"]},"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}}}},"CreateSubscriptionResponse":{"type":"object","required":["subscription","created"],"properties":{"created":{"type":"boolean"},"subscription":{"$ref":"#/components/schemas/Subscription"}}},"FeedItemSummary":{"type":"object","required":["id","title","subscription","created_at"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"author":{"type":["string","null"]},"url":{"type":["string","null"],"format":"uri"},"published_at":{"type":["integer","null"]},"summary":{"type":["string","null"]},"created_at":{"type":"integer"},"subscription":{"type":"object","required":["id","title","feed_url"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"feed_url":{"type":"string"}}}}},"ListFeedItemsResponse":{"type":"object","required":["items","next_cursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FeedItemSummary"}},"next_cursor":{"type":["string","null"]}}},"GetFeedItemResponse":{"type":"object","required":["item","next_content_cursor"],"properties":{"item":{"allOf":[{"$ref":"#/components/schemas/FeedItemSummary"},{"type":"object","properties":{"content_text":{"type":["string","null"]},"raw":{"type":"object","properties":{"content_raw":{"type":["string","null"]}}}}}]},"next_content_cursor":{"type":["string","null"]}}},"Artifact":{"type":"object","required":["artifact_id","status","type","viewer_url"],"properties":{"artifact_id":{"type":"string"},"type":{"type":"string","enum":["briefing_page","audio_brief"]},"status":{"type":"string"},"title":{"type":["string","null"]},"viewer_url":{"type":"string","format":"uri"},"audio_url":{"type":["string","null"],"format":"uri"},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"ArtifactCompositionResponse":{"type":"object","required":["artifact_id","status","viewer_url"],"properties":{"artifact_id":{"type":"string"},"status":{"type":"string"},"viewer_url":{"type":"string","format":"uri"}}},"ArtifactResponse":{"type":"object","required":["artifact"],"properties":{"artifact":{"$ref":"#/components/schemas/Artifact"}}},"ListArtifactsResponse":{"type":"object","required":["artifacts"],"properties":{"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/Artifact"}},"next_cursor":{"type":["string","null"]}}},"SettingsResponse":{"type":"object","properties":{"settings":{"type":"object","properties":{"app_theme":{"type":"string"},"default_timezone":{"type":"string"},"language":{"type":"string"}}}}}}}}