{
  "openapi": "3.1.0",
  "info": {
    "title": "Brifing Public API",
    "version": "1.0.0",
    "summary": "Read Brifing's sourced news summaries.",
    "description": "Read-only, anonymous access to Brifing's public stories: short, sourced summaries of business, technology, AI, finance and career news from 500+ publishers. No authentication. Responses are cached at the edge for a few minutes; please cite the publisher and `original_url` when you use a story.",
    "contact": {
      "name": "Horus Studios",
      "email": "hello@horusstudios.com",
      "url": "https://brifing.si/developers"
    },
    "termsOfService": "https://brifing.si/legal/terms"
  },
  "servers": [
    {
      "url": "https://brifing.si/api/v1"
    }
  ],
  "externalDocs": {
    "url": "https://brifing.si/developers",
    "description": "Developer docs (REST, MCP, A2A, Markdown)"
  },
  "paths": {
    "/stories": {
      "get": {
        "operationId": "listStories",
        "summary": "Latest stories, or search",
        "description": "Without `q`: newest stories, optionally for one topic. With `q`: stories whose headline contains every keyword, newest first.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 2
            },
            "description": "Search keywords."
          },
          {
            "name": "topic",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "business",
                "data-ai",
                "finance",
                "growth",
                "people",
                "entrepreneurship",
                "leadership",
                "operations",
                "engineering",
                "marketing",
                "product",
                "design",
                "sales"
              ]
            },
            "description": "Topic slug. Ignored when `q` is set."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "es",
                "fr",
                "de",
                "it",
                "pt",
                "ja",
                "ko",
                "ar"
              ],
              "default": "en"
            },
            "description": "Language for headlines and summaries; falls back to English."
          }
        ],
        "responses": {
          "200": {
            "description": "Stories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "stories",
                    "count",
                    "lang"
                  ],
                  "properties": {
                    "stories": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Story"
                      }
                    },
                    "count": {
                      "type": "integer"
                    },
                    "lang": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/stories/{id}": {
      "get": {
        "operationId": "getStory",
        "summary": "One story in full",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "es",
                "fr",
                "de",
                "it",
                "pt",
                "ja",
                "ko",
                "ar"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Story",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "story"
                  ],
                  "properties": {
                    "story": {
                      "$ref": "#/components/schemas/StoryDetail"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "Topics Brifing covers",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "es",
                "fr",
                "de",
                "it",
                "pt",
                "ja",
                "ko",
                "ar"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Topics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "categories": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Category"
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sources": {
      "get": {
        "operationId": "listSources",
        "summary": "Publishers Brifing follows",
        "responses": {
          "200": {
            "description": "Publishers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sources": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Source"
                      }
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "health",
        "summary": "API status",
        "responses": {
          "200": {
            "description": "Healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "503": {
            "description": "Degraded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Category": {
        "type": "object",
        "required": [
          "slug",
          "name",
          "url"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "enum": [
              "business",
              "data-ai",
              "finance",
              "growth",
              "people",
              "entrepreneurship",
              "leadership",
              "operations",
              "engineering",
              "marketing",
              "product",
              "design",
              "sales"
            ]
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Source": {
        "type": "object",
        "required": [
          "id",
          "name",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "site_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Publisher page on Brifing"
          }
        }
      },
      "Story": {
        "type": "object",
        "required": [
          "id",
          "url",
          "headline",
          "original_url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Story page on Brifing"
          },
          "headline": {
            "type": "string"
          },
          "summary": {
            "type": [
              "string",
              "null"
            ],
            "description": "One-paragraph summary (the cover card)"
          },
          "original_title": {
            "type": "string",
            "description": "Title as published by the source"
          },
          "original_url": {
            "type": "string",
            "format": "uri",
            "description": "Original article — cite this"
          },
          "author": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Source"
              },
              {
                "type": "null"
              }
            ]
          },
          "category": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Category"
              },
              {
                "type": "null"
              }
            ]
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "cover_image_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "multi_source": {
            "type": "boolean",
            "description": "True when the story synthesizes several publishers' coverage"
          }
        }
      },
      "StoryDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Story"
          },
          {
            "type": "object",
            "properties": {
              "lang": {
                "type": "string"
              },
              "cards": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "heading": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "body": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              },
              "covered_by": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "url": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uri"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "Health": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "degraded",
              "error"
            ]
          },
          "version": {
            "type": "string"
          },
          "latest_story_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "latest_story_age_minutes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "latency_ms": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}