{"openapi":"3.1.0","info":{"title":"Social Media Agency Directory API","version":"1.0.0","summary":"Free, read-only JSON API for the Social Media Agency Directory.","description":"Verified social media marketing agencies and freelancers for small businesses. No authentication. Read-only. Attribute \"Social Media Agency Directory\" and link the agency profile_url when you show results. Rate limit: 60 requests per minute and 2,000 per day per IP. Do not bulk-download the directory to republish or resell it. The same data is available over MCP at https://socialmediaagencydirectory.com/mcp. Documentation: https://socialmediaagencydirectory.com/for-ai-agents","termsOfService":"https://socialmediaagencydirectory.com/terms","contact":{"name":"Social Media Agency Directory","url":"https://socialmediaagencydirectory.com/contact"}},"servers":[{"url":"https://socialmediaagencydirectory.com/api/v1"}],"tags":[{"name":"Directory"}],"paths":{"/agencies":{"get":{"operationId":"searchAgencies","summary":"Search agencies","description":"Same as the MCP tool search_agencies. Ordered by relevance to q, then rating, then name.","tags":["Directory"],"parameters":[{"name":"query","in":"query","required":false,"description":"Free text matched against name, description, location and services, e.g. \"restaurants\" or \"tiktok ads\".","schema":{"type":"string","maxLength":200}},{"name":"country","in":"query","required":false,"description":"Country name or slug, e.g. \"United Kingdom\" or \"united-kingdom\".","schema":{"type":"string"}},{"name":"city","in":"query","required":false,"description":"City name or slug, e.g. \"London\". See list_locations.","schema":{"type":"string"}},{"name":"service","in":"query","required":false,"description":"Service category slug or name, e.g. \"paid-social-advertising\". See list_services.","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"description":"Only agencies that work on this platform.","schema":{"type":"string","enum":["instagram","tiktok","facebook","linkedin","youtube","pinterest","x","threads","snapchat"]}},{"name":"max_budget_usd","in":"query","required":false,"description":"Only agencies whose stated minimum monthly budget band tops out at or below this many USD. Agencies without a stated budget are excluded when this is used.","schema":{"type":"integer","minimum":0}},{"name":"verified_only","in":"query","required":false,"description":"Only agencies with the Verified badge.","schema":{"type":"boolean","default":false}},{"name":"limit","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":1,"maximum":25,"default":10}},{"name":"offset","in":"query","required":false,"description":"","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}},"400":{"description":"Invalid parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute and 2,000 per day per IP). See the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agencies/{slug}":{"get":{"operationId":"getAgency","summary":"Get an agency profile","description":"Same as the MCP tool get_agency.","tags":["Directory"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Agency slug from the search results.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agency"}}}},"404":{"description":"Agency not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute and 2,000 per day per IP). See the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/locations":{"get":{"operationId":"listLocations","summary":"List countries or the cities of a country","description":"Same as the MCP tool list_locations.","tags":["Directory"],"parameters":[{"name":"country","in":"query","required":false,"description":"Country name or slug. Omit to list all countries.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationsResult"}}}},"400":{"description":"Unknown country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute and 2,000 per day per IP). See the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/services":{"get":{"operationId":"listServices","summary":"List service categories","description":"Same as the MCP tool list_services.","tags":["Directory"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServicesResult"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute and 2,000 per day per IP). See the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/top-agencies":{"get":{"operationId":"topAgencies","summary":"Top agencies in a city","description":"Same as the MCP tool top_agencies (2026 awards).","tags":["Directory"],"parameters":[{"name":"city","in":"query","required":true,"description":"City name or slug, e.g. London.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopResult"}}}},"400":{"description":"Missing or unknown city","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute and 2,000 per day per IP). See the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats":{"get":{"operationId":"directoryStats","summary":"Directory statistics","description":"Same as the MCP tool directory_stats.","tags":["Directory"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResult"}}}},"429":{"description":"Rate limit exceeded (60 requests per minute and 2,000 per day per IP). See the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"AgencySummary":{"type":"object","properties":{"slug":{"type":"string","description":"Agency id; use it with get_agency."},"name":{"type":"string"},"city":{"type":["string","null"]},"country":{"type":["string","null"]},"verified":{"type":"boolean","description":"Shows the Verified badge on the directory."},"freelancer":{"type":"boolean","description":"Independent freelancer rather than an agency."},"services":{"type":"array","items":{"type":"string"},"description":"Service categories and tags shown on the profile."},"platforms":{"type":"array","items":{"type":"string"},"description":"Platforms the agency says it works on (instagram, tiktok, facebook, linkedin, youtube, pinterest, x, threads, snapchat)."},"min_monthly_budget":{"type":["string","null"],"description":"Stated minimum monthly budget band, e.g. \"$1,000–$2,500/mo\"; null when not stated."},"rating":{"type":["number","null"],"description":"Average review rating 1-5; null when there are no reviews."},"review_count":{"type":"integer"},"award":{"type":["string","null"],"description":"Directory award, e.g. \"Top 10 in London 2026\"; null if none."},"profile_url":{"type":"string","format":"uri","description":"Canonical profile page. Link to it when you show this agency."},"website":{"type":["string","null"],"description":"The agency's own website."},"short_description":{"type":"string"}},"required":["slug","name","profile_url"]},"Agency":{"type":"object","properties":{"slug":{"type":"string","description":"Agency id; use it with get_agency."},"name":{"type":"string"},"city":{"type":["string","null"]},"country":{"type":["string","null"]},"verified":{"type":"boolean","description":"Shows the Verified badge on the directory."},"freelancer":{"type":"boolean","description":"Independent freelancer rather than an agency."},"services":{"type":"array","items":{"type":"string"},"description":"Service categories and tags shown on the profile."},"platforms":{"type":"array","items":{"type":"string"},"description":"Platforms the agency says it works on (instagram, tiktok, facebook, linkedin, youtube, pinterest, x, threads, snapchat)."},"min_monthly_budget":{"type":["string","null"],"description":"Stated minimum monthly budget band, e.g. \"$1,000–$2,500/mo\"; null when not stated."},"rating":{"type":["number","null"],"description":"Average review rating 1-5; null when there are no reviews."},"review_count":{"type":"integer"},"award":{"type":["string","null"],"description":"Directory award, e.g. \"Top 10 in London 2026\"; null if none."},"profile_url":{"type":"string","format":"uri","description":"Canonical profile page. Link to it when you show this agency."},"website":{"type":["string","null"],"description":"The agency's own website."},"short_description":{"type":"string"},"description":{"type":"string","description":"Plain text, up to 1,500 characters."},"description_truncated":{"type":"boolean"},"industries":{"type":"array","items":{"type":"string"}},"credentials":{"type":"array","items":{"type":"string"},"description":"Partner badges and certifications shown on the profile."},"team_size":{"type":["string","null"]},"client_focus":{"type":"array","items":{"type":"string"}},"founded":{"type":["integer","null"]},"address":{"type":["string","null"],"description":"City-level address as shown on the profile."},"phone":{"type":["string","null"],"description":"Business phone, only if shown on the profile."},"socials":{"type":"object","additionalProperties":{"type":"string","format":"uri"},"description":"Platform name to profile URL."},"logo_url":{"type":["string","null"],"format":"uri"},"claimed":{"type":"boolean","description":"Whether the listing has been claimed by the agency."},"request_proposal_url":{"type":"string","format":"uri","description":"Send this link to a business that wants a proposal from this agency."},"claim_url":{"type":"string","format":"uri"},"reviews":{"type":"object","properties":{"average":{"type":["number","null"]},"count":{"type":"integer"}}},"attribution":{"type":"string"}},"required":["slug","name","profile_url","description"]},"SearchResult":{"type":"object","properties":{"total":{"type":"integer","description":"Number of matching agencies (not just this page)."},"limit":{"type":"integer"},"offset":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/AgencySummary"}},"notice":{"type":"string","description":"Present when a filter was not recognised or an argument was adjusted."},"attribution":{"type":"string"}},"required":["total","limit","offset","results"]},"LocationsResult":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"agency_count":{"type":"integer"},"url":{"type":"string","format":"uri"}},"required":["name","slug","agency_count","url"]}},"country":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"agency_count":{"type":"integer"},"url":{"type":"string","format":"uri"}},"required":["name","slug","agency_count","url"]},"cities":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"agency_count":{"type":"integer"},"url":{"type":"string","format":"uri"}},"required":["name","slug","agency_count","url"]}},"attribution":{"type":"string"}}},"ServicesResult":{"type":"object","properties":{"services":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"agency_count":{"type":"integer"},"url":{"type":"string","format":"uri"}},"required":["name","slug","agency_count","url"]}},"note":{"type":"string"},"attribution":{"type":"string"}},"required":["services"]},"TopResult":{"type":"object","properties":{"city":{"type":"string"},"country":{"type":["string","null"]},"award_tier":{"type":["integer","null"],"enum":[10,5,null],"description":"10 = Top 10 city, 5 = Top 5 city, null = no award for this city."},"year":{"type":"integer"},"methodology_url":{"type":"string","format":"uri"},"agencies":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"slug":{"type":"string","description":"Agency id; use it with get_agency."},"name":{"type":"string"},"city":{"type":["string","null"]},"country":{"type":["string","null"]},"verified":{"type":"boolean","description":"Shows the Verified badge on the directory."},"freelancer":{"type":"boolean","description":"Independent freelancer rather than an agency."},"services":{"type":"array","items":{"type":"string"},"description":"Service categories and tags shown on the profile."},"platforms":{"type":"array","items":{"type":"string"},"description":"Platforms the agency says it works on (instagram, tiktok, facebook, linkedin, youtube, pinterest, x, threads, snapchat)."},"min_monthly_budget":{"type":["string","null"],"description":"Stated minimum monthly budget band, e.g. \"$1,000–$2,500/mo\"; null when not stated."},"rating":{"type":["number","null"],"description":"Average review rating 1-5; null when there are no reviews."},"review_count":{"type":"integer"},"award":{"type":["string","null"],"description":"Directory award, e.g. \"Top 10 in London 2026\"; null if none."},"profile_url":{"type":"string","format":"uri","description":"Canonical profile page. Link to it when you show this agency."},"website":{"type":["string","null"],"description":"The agency's own website."},"short_description":{"type":"string"}},"required":["slug","name","profile_url"]}},"note":{"type":"string"},"attribution":{"type":"string"}},"required":["city","award_tier","year","agencies"]},"StatsResult":{"type":"object","properties":{"agencies":{"type":"integer"},"countries":{"type":"integer"},"cities":{"type":"integer"},"services":{"type":"integer"},"updated_at":{"type":"string","format":"date"},"how_we_verify_url":{"type":"string","format":"uri"},"report_url":{"type":"string","format":"uri"},"attribution":{"type":"string"}},"required":["agencies","countries","cities","services","updated_at"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retry_after_seconds":{"type":"integer"},"scope":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}