{
  "openapi": "3.1.0",
  "info": {
    "title": "Socials API",
    "version": "1.0.0",
    "summary": "Official channels (X, LinkedIn, YouTube, GitHub, Facebook, Instagram, TikTok, Threads, Bluesky, Mastodon, Hugging Face, Discord, community, Reddit, blog, newsletter, RSS, status, docs, careers) of every company in the companies.fru.dev registry, each verified against the company's own website or a back-link, with the evidence URL and the date checked",
    "description": "Official channels (X, LinkedIn, YouTube, GitHub, Facebook, Instagram, TikTok, Threads, Bluesky, Mastodon, Hugging Face, Discord, community, Reddit, blog, newsletter, RSS, status, docs, careers) of every company in the companies.fru.dev registry, each verified against the company's own website or a back-link, with the evidence URL and the date checked. Every company re-checked about once a month (a 28th of them daily at 04:40 UTC); the registry is synced daily and new registry companies are added and checked first, so the set grows with the registry. Free to read; please cite \"Socials (socials.fru.dev)\" with a link. Responses are cached at the edge; keep to about 60 requests a minute. Guide: https://socials.fru.dev/agents",
    "contact": {
      "name": "fru.dev",
      "url": "https://fru.dev",
      "email": "fru.dev3@gmail.com"
    }
  },
  "externalDocs": {
    "description": "For AI agents",
    "url": "https://socials.fru.dev/agents"
  },
  "servers": [
    {
      "url": "https://socials.fru.dev"
    }
  ],
  "paths": {
    "/api/companies": {
      "get": {
        "operationId": "list_companies",
        "summary": "Companies with their official links, verified or not, plus dated items (for the companies.fru.dev registry)",
        "description": "Companies with their official links, verified or not, plus dated items (for the companies.fru.dev registry). Returns companies with slug (companies.fru.dev slug), name, domain, category, page URL, check date and state, x_url / linkedin_url / github_url / youtube_url (verified only, else empty), every link with channel, url, handle, verified, basis, evidence URL and dates, registry_mismatch, and dated items.",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "Only companies checked or changed at or after this date (YYYY-MM-DD)",
            "schema": {
              "type": "string"
            },
            "example": "2026-09-01"
          },
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "description": "Only companies with a link on this channel",
            "schema": {
              "type": "string",
              "enum": [
                "website",
                "x",
                "linkedin",
                "youtube",
                "github",
                "facebook",
                "instagram",
                "tiktok",
                "threads",
                "bluesky",
                "mastodon",
                "huggingface",
                "discord",
                "community",
                "reddit",
                "blog",
                "newsletter",
                "rss",
                "status",
                "docs",
                "careers"
              ]
            },
            "example": "github"
          },
          {
            "name": "verified",
            "in": "query",
            "required": false,
            "description": "With channel: only verified links on it. Alone: only companies with at least one verified link",
            "schema": {
              "type": "boolean"
            },
            "example": true
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 200",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 200
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Items to skip, for the next page",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "companies with slug (companies.fru.dev slug), name, domain, category, page URL, check date and state, x_url / linkedin_url / github_url / youtube_url (verified only, else empty), every link with channel, url, handle, verified, basis, evidence URL and dates, registry_mismatch, and dated items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "companies": [
                    {
                      "slug": "adobe",
                      "name": "Adobe",
                      "domain": "adobe.com",
                      "category": "Software",
                      "url": "https://socials.fru.dev/companies/adobe",
                      "registry": "https://companies.fru.dev/companies/adobe",
                      "checked": "2026-09-24",
                      "check_state": "ok",
                      "x_url": "",
                      "linkedin_url": "https://www.linkedin.com/company/adobe",
                      "github_url": "https://github.com/adobe",
                      "youtube_url": "https://www.youtube.com/user/AdobeSystems",
                      "verified": 4,
                      "links": [
                        {
                          "channel": "website",
                          "url": "https://www.adobe.com",
                          "handle": "adobe.com",
                          "verified": true,
                          "basis": "site",
                          "evidence": "https://www.adobe.com/",
                          "since": "2026-09-24",
                          "checked": "2026-09-24"
                        },
                        {
                          "channel": "x",
                          "url": "https://x.com/Adobe",
                          "handle": "@Adobe",
                          "verified": false,
                          "basis": "registry",
                          "evidence": "https://companies.fru.dev/companies/adobe",
                          "since": "2026-09-24",
                          "checked": "2026-09-24"
                        }
                      ]
                    },
                    {
                      "slug": "ai-engineer",
                      "name": "AI Engineer",
                      "domain": "ai.engineer",
                      "category": "Events and community",
                      "url": "https://socials.fru.dev/companies/ai-engineer",
                      "registry": "https://companies.fru.dev/companies/ai-engineer",
                      "checked": "2026-09-24",
                      "check_state": "ok",
                      "x_url": "https://x.com/aidotengineer",
                      "linkedin_url": "https://www.linkedin.com/company/aidotengineer",
                      "github_url": "https://github.com/aiDotEngineer",
                      "youtube_url": "https://www.youtube.com/@aiDotEngineer",
                      "verified": 4,
                      "links": [
                        {
                          "channel": "website",
                          "url": "https://ai.engineer",
                          "handle": "ai.engineer",
                          "verified": true,
                          "basis": "site",
                          "evidence": "https://ai.engineer/",
                          "since": "2026-09-24",
                          "checked": "2026-09-24"
                        },
                        {
                          "channel": "x",
                          "url": "https://x.com/aidotengineer",
                          "handle": "@aidotengineer",
                          "verified": true,
                          "basis": "site",
                          "evidence": "https://ai.engineer/",
                          "since": "2026-09-24",
                          "checked": "2026-09-24"
                        }
                      ]
                    }
                  ],
                  "total": 107,
                  "limit": 2,
                  "offset": 0,
                  "next": "/api/companies?channel=github&verified=1&limit=2&offset=2",
                  "note": "verified = the company's own site links it (basis site) or the profile links back to its domain (basis backlink); unverified links come f..."
                }
              }
            }
          }
        }
      }
    },
    "/api/companies/{slug}": {
      "get": {
        "operationId": "get_company",
        "summary": "One company's official links with evidence and history",
        "description": "One company's official links with evidence and history. Returns the company with every link, its evidence and dates, the registry mismatches, dated items and its change history.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The companies.fru.dev slug, as in /companies/<slug>",
            "schema": {
              "type": "string"
            },
            "example": "databricks"
          }
        ],
        "responses": {
          "200": {
            "description": "the company with every link, its evidence and dates, the registry mismatches, dated items and its change history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "company": {
                    "slug": "databricks",
                    "name": "Databricks",
                    "domain": "databricks.com",
                    "category": "Data",
                    "url": "https://socials.fru.dev/companies/databricks",
                    "registry": "https://companies.fru.dev/companies/databricks",
                    "checked": "2026-09-24",
                    "check_state": "ok",
                    "x_url": "https://x.com/databricks",
                    "linkedin_url": "https://www.linkedin.com/company/databricks",
                    "github_url": "https://github.com/databricks",
                    "youtube_url": "https://www.youtube.com/@Databricks",
                    "verified": 9,
                    "links": [
                      {
                        "channel": "website",
                        "url": "https://www.databricks.com",
                        "handle": "databricks.com",
                        "verified": true,
                        "basis": "site",
                        "evidence": "https://www.databricks.com/",
                        "since": "2026-09-24",
                        "checked": "2026-09-24"
                      },
                      {
                        "channel": "x",
                        "url": "https://x.com/databricks",
                        "handle": "@databricks",
                        "verified": true,
                        "basis": "site",
                        "evidence": "https://www.databricks.com/",
                        "since": "2026-09-24",
                        "checked": "2026-09-24"
                      }
                    ]
                  },
                  "note": "verified = the company's own site links it (basis site) or the profile links back to its domain (basis backlink); unverified links come f..."
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/api/channels": {
      "get": {
        "operationId": "list_channels",
        "summary": "The channels tracked and how many companies have a verified link on each",
        "description": "The channels tracked and how many companies have a verified link on each. Returns channels with id, label, kind (social or first-party), description and counts of verified and unverified companies.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "channels with id, label, kind (social or first-party), description and counts of verified and unverified companies",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "channels": [
                    {
                      "id": "x",
                      "label": "X",
                      "kind": "social",
                      "description": "Official X (Twitter) accounts",
                      "verified": 239,
                      "unverified": 69,
                      "url": "https://socials.fru.dev/channels/x"
                    },
                    {
                      "id": "linkedin",
                      "label": "LinkedIn",
                      "kind": "social",
                      "description": "Official LinkedIn company pages",
                      "verified": 256,
                      "unverified": 34,
                      "url": "https://socials.fru.dev/channels/linkedin"
                    }
                  ],
                  "companies": 566
                }
              }
            }
          }
        }
      }
    },
    "/api/changes": {
      "get": {
        "operationId": "list_changes",
        "summary": "The append-only history: links added, changed (handle renames), verified, unverified and removed, newest first",
        "description": "The append-only history: links added, changed (handle renames), verified, unverified and removed, newest first. Returns changes with time, company slug, channel, change, old and new URL, the page it was seen on, and who (seed, agent, admin).",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "Only changes at or after this date (YYYY-MM-DD)",
            "schema": {
              "type": "string"
            },
            "example": "2026-09-01"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 200",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 200
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Items to skip, for the next page",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "changes with time, company slug, channel, change, old and new URL, the page it was seen on, and who (seed, agent, admin)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "changes": [
                    {
                      "at": "2026-09-24 23:17:07",
                      "company": "zscaler",
                      "channel": "careers",
                      "change": "added",
                      "old": "",
                      "new": "https://www.zscaler.com/careers",
                      "source": "https://www.zscaler.com/",
                      "by": "seed"
                    },
                    {
                      "at": "2026-09-24 23:17:07",
                      "company": "zscaler",
                      "channel": "blog",
                      "change": "added",
                      "old": "",
                      "new": "https://www.zscaler.com/blogs",
                      "source": "https://www.zscaler.com/",
                      "by": "seed"
                    }
                  ],
                  "total": 600,
                  "limit": 3,
                  "offset": 0,
                  "next": "/api/changes?limit=3&offset=3",
                  "note": "Newest 600 changes; the history is append-only. by = seed marks the first check."
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "operationId": "search",
        "summary": "Search companies (by name, domain or any handle) and pages",
        "description": "Search companies (by name, domain or any handle) and pages. Returns up to 20 ranked results with title, link and one line.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Company name, domain or handle",
            "schema": {
              "type": "string"
            },
            "example": "snowflake"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Results, 1 to 20",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "up to 20 ranked results with title, link and one line",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "q": "snowflake",
                  "results": [
                    {
                      "id": "co:snowflake",
                      "group": "companies",
                      "title": "Snowflake",
                      "subtitle": "7 verified: X, LinkedIn, YouTube, Facebook",
                      "href": "/companies/snowflake",
                      "keywords": [
                        "snowflake",
                        "snowflake.com"
                      ],
                      "logo": "https://img.logo.dev/snowflake.com?token=...&size=64&format=png&theme=light&retina=true&fallback=404",
                      "boost": 14,
                      "score": 1064
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}