{
 "openapi": "3.1.0",
 "info": {
  "title": "Social signals: organisations' public posts, by link: data.promptugal.news",
  "version": "v0.1.47",
  "description": "Links to recent public posts by the official accounts of organisations (câmaras, public bodies, venues, organisers, news outlets, companies) on Bluesky and Mastodon, with metadata only: account, time, matched topics and places, language, media or not. No post text or media is stored.\n\nPublisher: The organisations themselves, through Bluesky (public AppView API) and Mastodon (public instance API). Reuse terms: Organisations only, official interfaces only, by link. Bluesky: robots.txt of the public API allows crawling it and asks for backoff on 429; the Terms of Service (14 Aug 2025) leave each post's content with its author, so we store link and metadata only and credit the organisation. Mastodon: mastodon.social's terms (effective 2026-08-31) say whoever owns the content retains ownership and allow API access; its robots.txt disallows only /media_proxy/, /interact/ and a domain-blocks path. Licence on each post: the platform's terms, holder the organisation. Not reviewed by a person. Not a warning service: follow IPMA and ANEPC.\n\nCode: Apache-2.0. Text: CC BY 4.0. The data keeps the terms of its own source (see each source card); nothing here relaxes them.",
  "license": {
   "name": "Apache-2.0 for code; each source keeps its own data terms",
   "identifier": "Apache-2.0"
  },
  "contact": {
   "name": "PrompTugal.news data",
   "url": "https://github.com/PrompTugal/PrompTugal__News__Data"
  }
 },
 "servers": [
  {
   "url": "https://data.promptugal.news",
   "description": "Production"
  }
 ],
 "externalDocs": {
  "description": "How to use the API",
  "url": "https://data.promptugal.news/api/"
 },
 "paths": {
  "/api/v1/social/latest.json": {
   "get": {
    "operationId": "get_social_latest",
    "tags": [
     "social"
    ],
    "summary": "Social signals: organisations' public posts, by link: the latest read",
    "description": "Links to recent public posts (last 30 days) by the official accounts of organisations (câmaras, public bodies, venues, organisers, news outlets, companies) listed in register/social-accounts.json. Each record is the post's public web address plus metadata: who, when, which topics and places its text matched, language, whether it has media. The post text and media are not stored: open the link, or use the platform's own embed, to see the post. Every post stays its author's content under the platform's terms; show it by link, credited to the organisation. A signal to check, not a verified fact. Never a private person's account.",
    "responses": {
     "200": {
      "description": "The file",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "source": {
           "type": "string"
          },
          "title": {
           "type": "string"
          },
          "read_at": {
           "type": "string"
          },
          "provenance": {
           "type": "object",
           "properties": {
            "source": {
             "type": "string"
            },
            "page": {
             "type": "string"
            },
            "read_at": {
             "type": "string"
            },
            "by": {
             "type": "string"
            },
            "terms": {
             "type": "string"
            },
            "sources": {
             "type": "array",
             "items": {
              "type": "object",
              "properties": {
               "platform": {
                "type": "string"
               },
               "api": {
                "type": "string"
               },
               "terms": {
                "type": "string"
               },
               "note": {
                "type": "string"
               }
              },
              "required": [
               "platform",
               "api",
               "terms",
               "note"
              ]
             }
            },
            "accounts": {
             "type": "string"
            }
           },
           "required": [
            "source",
            "page",
            "read_at",
            "by",
            "terms",
            "sources",
            "accounts"
           ]
          },
          "about": {
           "type": "string"
          },
          "counts": {
           "type": "object",
           "properties": {
            "posts": {
             "type": "integer"
            },
            "accounts": {
             "type": "integer"
            },
            "by_platform": {
             "type": "object",
             "properties": {
              "bluesky": {
               "type": "integer"
              },
              "mastodon": {
               "type": "integer"
              }
             },
             "required": [
              "bluesky",
              "mastodon"
             ]
            },
            "with_topic": {
             "type": "integer"
            },
            "with_place": {
             "type": "integer"
            }
           },
           "required": [
            "posts",
            "accounts",
            "by_platform",
            "with_topic",
            "with_place"
           ]
          },
          "posts": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "platform": {
              "type": "string"
             },
             "url": {
              "type": "string",
              "format": "uri"
             },
             "account": {
              "type": "string"
             },
             "organisation": {
              "type": "string"
             },
             "kind": {
              "type": "string"
             },
             "posted_at": {
              "type": "string"
             },
             "topics": {
              "type": "array",
              "items": {
               "type": "string"
              }
             },
             "places": {
              "type": "array",
              "items": {
               "type": "string"
              }
             },
             "lang": {
              "type": "null"
             },
             "has_media": {
              "type": "boolean"
             },
             "source": {
              "type": "string"
             },
             "license": {
              "type": "object",
              "properties": {
               "name": {
                "type": "string"
               },
               "url": {
                "type": "string",
                "format": "uri"
               },
               "holder": {
                "type": "string"
               }
              },
              "required": [
               "name",
               "url",
               "holder"
              ]
             },
             "read_at": {
              "type": "string"
             }
            },
            "required": [
             "platform",
             "url",
             "account",
             "organisation",
             "kind",
             "posted_at",
             "topics",
             "places",
             "lang",
             "has_media",
             "source",
             "license",
             "read_at"
            ]
           }
          },
          "gaps": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "what": {
              "type": "string"
             },
             "why": {
              "type": "string"
             },
             "read_at": {
              "type": "string"
             }
            },
            "required": [
             "what",
             "why",
             "read_at"
            ]
           }
          }
         },
         "required": [
          "source",
          "title",
          "read_at",
          "provenance",
          "about",
          "counts",
          "posts",
          "gaps"
         ],
         "x-inferred": true
        },
        "examples": {
         "example": {
          "summary": "A real file, cut to a readable size",
          "value": {
           "source": "social",
           "title": "Social signals: organisations' public posts, by link",
           "read_at": "2026-11-18T19:17:54Z",
           "provenance": {
            "source": "https://public.api.bsky.app/xrpc/",
            "page": "https://bsky.app/",
            "read_at": "2026-11-18T19:17:54Z",
            "by": "sources/social/collect.mjs (code, no model; run by data.b@PrompTugal.dinis)",
            "terms": "Organisations only, official interfaces only, by link. Bluesky: robots.txt of the public API allows crawling it and asks for backoff on 429; the Terms of Service (14 Aug 2025) leave each post's content with its author, so we store link and metadata only and credit the organisation. Mastodon: mastodo...",
            "sources": [
             {
              "platform": "bluesky",
              "api": "https://public.api.bsky.app/xrpc",
              "terms": "https://bsky.social/about/support/tos",
              "note": "public AppView, no login"
             },
             {
              "platform": "mastodon",
              "api": "https://<instance>/api/v1/",
              "terms": "https://<instance>/terms-of-service",
              "note": "public endpoints, without credentials"
             }
            ],
            "accounts": "register/social-accounts.json"
           },
           "about": "Links to recent public posts (last 30 days) by the official accounts of organisations (câmaras, public bodies, venues, organisers, news outlets, companies) listed in register/social-accounts.json. Each record is the post's public web address plus metadata: who, when, which topics and places its text...",
           "counts": {
            "posts": 147,
            "accounts": 5,
            "by_platform": {
             "bluesky": 147,
             "mastodon": 0
            },
            "with_topic": 21,
            "with_place": 27
           },
           "posts": [
            {
             "platform": "bluesky",
             "url": "https://bsky.app/profile/publico.pt/post/3n2mbdycphl2i",
             "account": "publico.pt",
             "organisation": "Público",
             "kind": "news outlet",
             "posted_at": "2026-11-18T19:15:01.6892444Z",
             "topics": [],
             "places": [],
             "lang": null,
             "has_media": true,
             "source": "author feed",
             "license": {
              "name": "the platform's terms",
              "url": "https://bsky.social/about/support/tos",
              "holder": "Público"
             },
             "read_at": "2026-11-18T19:17:54Z"
            },
            {
             "platform": "bluesky",
             "url": "https://bsky.app/profile/publico.pt/post/3n2mbdxahr32i",
             "account": "publico.pt",
             "organisation": "Público",
             "kind": "news outlet",
             "posted_at": "2026-11-18T19:15:00.566859Z",
             "topics": [],
             "places": [],
             "lang": null,
             "has_media": true,
             "source": "author feed",
             "license": {
              "name": "the platform's terms",
              "url": "https://bsky.social/about/support/tos",
              "holder": "Público"
             },
             "read_at": "2026-11-18T19:17:54Z"
            },
            {
             "platform": "bluesky",
             "url": "https://bsky.app/profile/publico.pt/post/3n2mbdwia7p2b",
             "account": "publico.pt",
             "organisation": "Público",
             "kind": "news outlet",
             "posted_at": "2026-11-18T19:14:59.7727381Z",
             "topics": [],
             "places": [],
             "lang": null,
             "has_media": true,
             "source": "author feed",
             "license": {
              "name": "the platform's terms",
              "url": "https://bsky.social/about/support/tos",
              "holder": "Público"
             },
             "read_at": "2026-11-18T19:17:54Z"
            }
           ],
           "gaps": [
            {
             "what": "Bluesky keyword search \"\"Web Summit\"\"",
             "why": "not read: the public search was refused or failed (see reads.json); the author feeds above still cover the listed accounts",
             "read_at": "2026-11-18T19:17:54Z"
            },
            {
             "what": "Bluesky keyword search \"Lisboa\"",
             "why": "not read: the public search was refused or failed (see reads.json); the author feeds above still cover the listed accounts",
             "read_at": "2026-11-18T19:17:54Z"
            },
            {
             "what": "Bluesky keyword search \"Algarve\"",
             "why": "not read: the public search was refused or failed (see reads.json); the author feeds above still cover the listed accounts",
             "read_at": "2026-11-18T19:17:54Z"
            }
           ]
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "No such file"
     }
    }
   }
  },
  "/api/v1/social/reads.json": {
   "get": {
    "operationId": "get_social_reads",
    "tags": [
     "social"
    ],
    "summary": "Social signals: organisations' public posts, by link: every read, newest first",
    "description": "Every run of sources/social/collect.mjs, newest first: each request's address, HTTP status, size, the first 16 hex of its sha256, and whether the bytes changed since the run before. The bytes and the full sha256 go to the source's vault (see card.json: latest/reads-full.json), never to git.",
    "responses": {
     "200": {
      "description": "The file",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "about": {
           "type": "string"
          },
          "source": {
           "type": "string"
          },
          "runs": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "at": {
              "type": "string"
             },
             "finished": {
              "type": "string"
             },
             "ok": {
              "type": "integer"
             },
             "failed": {
              "type": "integer"
             },
             "reads": {
              "type": "array",
              "items": {
               "type": "object",
               "properties": {
                "name": {
                 "type": "string"
                },
                "url": {
                 "type": "string",
                 "format": "uri"
                },
                "at": {
                 "type": "string"
                },
                "status": {
                 "type": "integer"
                },
                "bytes": {
                 "type": "integer"
                },
                "sha256_prefix": {
                 "type": "string"
                },
                "changed": {
                 "type": "boolean"
                }
               },
               "required": [
                "name",
                "url",
                "at",
                "status",
                "bytes",
                "sha256_prefix",
                "changed"
               ]
              }
             }
            },
            "required": [
             "at",
             "finished",
             "ok",
             "failed",
             "reads"
            ]
           }
          }
         },
         "required": [
          "about",
          "source",
          "runs"
         ],
         "x-inferred": true
        },
        "examples": {
         "example": {
          "summary": "A real file, cut to a readable size",
          "value": {
           "about": "Every run of sources/social/collect.mjs, newest first: each request's address, HTTP status, size, the first 16 hex of its sha256, and whether the bytes changed since the run before. The bytes and the full sha256 go to the source's vault (see card.json: latest/reads-full.json), never to git.",
           "source": "social",
           "runs": [
            {
             "at": "2026-11-18T19:17:54Z",
             "finished": "2026-11-18T19:18:17Z",
             "ok": 5,
             "failed": 5,
             "reads": [
              {
               "name": "bsky-feed-bsky-visitportugal",
               "url": "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=visitportugal.com&filter=posts_no_replies&limit=30",
               "at": "2026-11-18T19:17:54Z",
               "status": 200,
               "bytes": 80888,
               "sha256_prefix": "9eb91a086fac7732",
               "changed": false
              },
              {
               "name": "bsky-feed-bsky-publico",
               "url": "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=publico.pt&filter=posts_no_replies&limit=30",
               "at": "2026-11-18T19:17:57Z",
               "status": 200,
               "bytes": 78366,
               "sha256_prefix": "c6cd9cbbdc570a7d",
               "changed": true
              },
              {
               "name": "bsky-feed-bsky-lusa",
               "url": "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=lusa.pt&filter=posts_no_replies&limit=30",
               "at": "2026-11-18T19:17:59Z",
               "status": 200,
               "bytes": 60549,
               "sha256_prefix": "390038803d9aaffb",
               "changed": false
              }
             ]
            },
            {
             "at": "2026-11-18T19:12:30Z",
             "finished": "2026-11-18T19:12:54Z",
             "ok": 5,
             "failed": 5,
             "reads": [
              {
               "name": "bsky-feed-bsky-visitportugal",
               "url": "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=visitportugal.com&filter=posts_no_replies&limit=30",
               "at": "2026-11-18T19:12:31Z",
               "status": 200,
               "bytes": 80888,
               "sha256_prefix": "9eb91a086fac7732",
               "changed": false
              },
              {
               "name": "bsky-feed-bsky-publico",
               "url": "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=publico.pt&filter=posts_no_replies&limit=30",
               "at": "2026-11-18T19:12:34Z",
               "status": 200,
               "bytes": 78524,
               "sha256_prefix": "9c71f5ba6b1948de",
               "changed": false
              },
              {
               "name": "bsky-feed-bsky-lusa",
               "url": "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=lusa.pt&filter=posts_no_replies&limit=30",
               "at": "2026-11-18T19:12:36Z",
               "status": 200,
               "bytes": 60549,
               "sha256_prefix": "390038803d9aaffb",
               "changed": false
              }
             ]
            },
            {
             "at": "2026-11-18T19:08:59Z",
             "finished": "2026-11-18T19:09:22Z",
             "ok": 5,
             "failed": 5,
             "reads": [
              {
               "name": "bsky-feed-bsky-visitportugal",
               "url": "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=visitportugal.com&filter=posts_no_replies&limit=30",
               "at": "2026-11-18T19:08:59Z",
               "status": 200,
               "bytes": 80888,
               "sha256_prefix": "9eb91a086fac7732",
               "changed": false
              },
              {
               "name": "bsky-feed-bsky-publico",
               "url": "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=publico.pt&filter=posts_no_replies&limit=30",
               "at": "2026-11-18T19:09:02Z",
               "status": 200,
               "bytes": 78524,
               "sha256_prefix": "9c71f5ba6b1948de",
               "changed": false
              },
              {
               "name": "bsky-feed-bsky-lusa",
               "url": "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=lusa.pt&filter=posts_no_replies&limit=30",
               "at": "2026-11-18T19:09:04Z",
               "status": 200,
               "bytes": 60549,
               "sha256_prefix": "390038803d9aaffb",
               "changed": false
              }
             ]
            }
           ]
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "No such file"
     }
    }
   }
  },
  "/api/v1/social/card.json": {
   "get": {
    "operationId": "get_social_card",
    "tags": [
     "social"
    ],
    "summary": "Social signals: organisations' public posts, by link: the card",
    "description": "Who publishes the source, its reuse terms, the schedule, who owns it, what runs by code, by agents and by people, and the vault.",
    "responses": {
     "200": {
      "description": "The file",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "string"
          },
          "title": {
           "type": "string"
          },
          "what": {
           "type": "string"
          },
          "publisher": {
           "type": "string"
          },
          "owner": {
           "type": "string"
          },
          "collector": {
           "type": "string"
          },
          "source_home": {
           "type": "string"
          },
          "reader_page": {
           "type": "string"
          },
          "schedule": {
           "type": "object",
           "properties": {
            "cadence": {
             "type": "string"
            },
            "how": {
             "type": "string"
            }
           },
           "required": [
            "cadence",
            "how"
           ]
          },
          "terms": {
           "type": "object",
           "properties": {
            "summary": {
             "type": "string"
            },
            "page": {
             "type": "string"
            },
            "read_at": {
             "type": "string"
            },
            "quote": {
             "type": "string"
            },
            "quote_lang": {
             "type": "string"
            },
            "republish": {
             "type": "string"
            },
            "open_question": {
             "type": "string"
            }
           },
           "required": [
            "summary",
            "page",
            "read_at",
            "quote",
            "quote_lang",
            "republish",
            "open_question"
           ]
          },
          "api": {
           "type": "object",
           "properties": {
            "latest": {
             "type": "string"
            },
            "reads": {
             "type": "string"
            },
            "card": {
             "type": "string"
            },
            "openapi": {
             "type": "string"
            },
            "page": {
             "type": "string"
            }
           },
           "required": [
            "latest",
            "reads",
            "card",
            "openapi",
            "page"
           ]
          },
          "vault": {
           "type": "null"
          },
          "split": {
           "type": "object",
           "properties": {
            "code": {
             "type": "array",
             "items": {
              "type": "string"
             }
            },
            "agents": {
             "type": "array",
             "items": {
              "type": "string"
             }
            },
            "people": {
             "type": "array",
             "items": {
              "type": "string"
             }
            }
           },
           "required": [
            "code",
            "agents",
            "people"
           ]
          },
          "cost": {
           "type": "object",
           "properties": {
            "per_run_tokens": {
             "type": "integer"
            },
            "per_run_model_cost_usd": {
             "type": "integer"
            },
            "runner": {
             "type": "string"
            },
            "build_tokens": {
             "type": "string"
            },
            "note": {
             "type": "string"
            }
           },
           "required": [
            "per_run_tokens",
            "per_run_model_cost_usd",
            "runner",
            "build_tokens",
            "note"
           ]
          },
          "since": {
           "type": "string"
          }
         },
         "required": [
          "id",
          "title",
          "what",
          "publisher",
          "owner",
          "collector",
          "source_home",
          "reader_page",
          "schedule",
          "terms",
          "api",
          "vault",
          "split",
          "cost",
          "since"
         ],
         "x-inferred": true
        },
        "examples": {
         "example": {
          "summary": "A real file, cut to a readable size",
          "value": {
           "id": "social",
           "title": "Social signals: organisations' public posts, by link",
           "what": "Links to recent public posts by the official accounts of organisations (câmaras, public bodies, venues, organisers, news outlets, companies) on Bluesky and Mastodon, with metadata only: account, time, matched topics and places, language, media or not. No post text or media is stored.",
           "publisher": "The organisations themselves, through Bluesky (public AppView API) and Mastodon (public instance API)",
           "owner": "data.b@PrompTugal.dinis",
           "collector": "sources/social/collect.mjs",
           "source_home": "https://public.api.bsky.app/xrpc/",
           "reader_page": "https://bsky.app/",
           "schedule": {
            "cadence": "every 6 hours",
            "how": "the Pages workflow (.github/workflows/pages.yml) at 17 minutes past 00, 06, 12 and 18 UTC; every other hourly run keeps the last read, copied from the live site"
           },
           "terms": {
            "summary": "Organisations only, official interfaces only, by link. Bluesky: robots.txt of the public API allows crawling it and asks for backoff on 429; the Terms of Service (14 Aug 2025) leave each post's content with its author, so we store link and metadata only and credit the organisation. Mastodon: mastodo...",
            "page": "https://public.api.bsky.app/robots.txt",
            "read_at": "2026-11-18",
            "quote": "Crawling the public parts of the API is allowed. HTTP 429 (\"backoff\") status codes are used for rate-limiting. Up to a handful concurrent requests should be ok.",
            "quote_lang": "en",
            "republish": "links and metadata only, credited to the organisation, under the platform's terms; no post text or media republished",
            "open_question": "Dinis to confirm the Bluesky terms (https://bsky.social/about/support/tos) are enough for links plus metadata, and which more organisation accounts to add (register/social-accounts.json notes)."
           },
           "api": {
            "latest": "https://data.promptugal.news/api/v1/social/latest.json",
            "reads": "https://data.promptugal.news/api/v1/social/reads.json",
            "card": "https://data.promptugal.news/api/v1/social/card.json",
            "openapi": "https://data.promptugal.news/api/v1/social/openapi.json",
            "page": "https://data.promptugal.news/sources/social/"
           },
           "vault": null,
           "split": {
            "code": [
             "the collector reads each listed account's recent posts and a keyword pass on Bluesky, keeps only links and metadata, and writes latest.json and reads.json",
             "collect/social-by-place.mjs derives data/social/by-place/<place>.json from latest.json",
             "GitHub Actions runs it and deploys the site"
            ],
            "agents": [
             "data.b.collector@PrompTugal.dinis (Sonnet) researched the platforms' terms and the accounts and wrote the collector and this card on 18 November 2026, for data.b@PrompTugal.dinis"
            ],
            "people": [
             "Dinis Cruz decided the social signals on 18 November 2026 (board/guidance/2026-11-18-social-signals.md); no person has checked the accounts or values yet (not reviewed)"
            ]
           },
           "cost": {
            "per_run_tokens": 0,
            "per_run_model_cost_usd": 0,
            "runner": "GitHub Actions on a public repository: no charge; about 10 requests a run (measured locally, 18 November 2026)",
            "build_tokens": "not measured",
            "note": "Code only: no model is called when the data is collected."
           },
           "since": "2026-11-18"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "No such file"
     }
    }
   }
  },
  "/api/v1/social/openapi.json": {
   "get": {
    "operationId": "get_social_openapi",
    "tags": [
     "social"
    ],
    "summary": "Social signals: organisations' public posts, by link: this document",
    "responses": {
     "200": {
      "description": "The file",
      "content": {
       "application/json": {
        "schema": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  }
 },
 "tags": [
  {
   "name": "social",
   "description": "Links to recent public posts by the official accounts of organisations (câmaras, public bodies, venues, organisers, news outlets, companies) on Bluesky and Mastodon, with metadata only: account, time, matched topics and places, language, media or not. No post text or media is stored."
  }
 ],
 "x-source": {
  "id": "social",
  "card": "https://data.promptugal.news/api/v1/social/card.json",
  "page": "https://data.promptugal.news/sources/social/"
 }
}
