The Walls.io Social Media API lets you pull posts from every connected network through one endpoint, cache them, and render your own live feed. You call GET /posts with an access token, hold the JSON for five minutes, and display it however you want. This guide shows you how, with working PHP and JavaScript, plus a prompt you can hand to any AI coding agent.
You do not have to write much of it yourself, either. The same prompt works in Claude Code, Cursor, OpenAI Codex, ChatGPT, Grok Build, GitHub Copilot, and Google Antigravity, so you can pick whichever tool you already have open.
A social wall is a single feed that shows posts from many social networks in one place. If you want the background on what a social media wall is, the Walls.io knowledge base covers it in depth. Most projects that use the social media API fit into one of three categories.
The first is the event feed. You put a live stream of attendee posts, hashtags, and mentions on a big screen at a conference or concert. People spot their own post on the wall, and they keep posting. This guide has lots of ideas for using social media at events.
The second is the website widget. This is a feed of your brand’s social content. It is embedded on a homepage or campaign page. It adds fresh, user-generated social media content. No one has to update it by hand.
The third is digital signage, where the same video is shown on screens in stores, lobbies, or stadiums. You can control how things look on a video wall or in-store display. To see what they look like in real life, look at some social wall examples.
The hard part in all three is the same. It’s difficult to get good, reliable content from a dozen different platforms. That’s what a social media API built for aggregation does.
Every network ships its own API, its own auth flow, its own data shape, and its own review process, and those change without asking you. Wire up each one yourself, and you are maintaining a dozen brittle integrations, then patching them every time a platform moves the goalposts.
Walls.io is a Meta-API instead: you connect once and get Social Media Aggregation – collect content from social media and display it anywhere – across every supported network in a single JSON format. The fields are normalized, so a post from one network arrives with the same shape as a post from another. You write your rendering logic a single time, and add or remove sources in your settings without touching the code. It is plain HTTP and JSON, so there is nothing exotic to learn, and what you do with the data is entirely yours.
Start your free Walls.io social wall trial, then come back and point your agent at the docs.
Try it free – no credit card needed, then come back and point your agent at the docs.
Every request is tied to one wall and authenticated with an access token. Open your wall’s settings in the Walls.io dashboard, find the API section, and click Activate API access. Copy the token it gives you.
This runs through API Access – use a single API to integrate and manage content from multiple networks and platforms – which is available on all paid Walls.io plans. You can check the tiers on the pricing page, and the full reference lives in the Walls.io API docs on GitHub.
Which endpoint do you need?
All endpoints sit under https://api.walls.io/v1. For a feed, you need exactly one of them: GET /posts. The smallest useful request looks like this.
GET https://api.walls.io/v1/posts?access_token=YOUR_TOKEN&fields=id,comment,type&limit=10A handful of query parameters do most of the work. access_token is required. limit sets how many posts you get, up to 1000 (the default is 50). fields is a comma-separated list of the fields you want back, which keeps responses small. sort orders the result by any field, with a leading minus for descending order. Watch this one: the default -id order reflects when posts reached Walls.io, not when they were posted, so for display you almost always want -created_timestamp. There are also optional types, media_types and languages filters when you need them.
Each post comes back with fields like id, type (the network), comment (the text), external_fullname (the author), post_image_cdn and external_image_cdn (cached images), permalink (the original post) and created_timestamp.
One rule matters more than the rest. The API does not support CORS, and your token must stay private, so every call happens on the server. Never in the browser. Both examples below follow that rule.
How do you fetch, cache, and display the posts?
The shape is the same in any language. Get the posts, save them for five minutes so you stay within the rate limit, and then show the feed from the saved posts. If the API malfunctions, you should serve the last good copy instead of a blank screen. This is exactly the kind of thing an AI agent is good at, but it helps to know the goal.
PHP
Save this as index.php and set your token. It caches to a local JSON file, refreshes only when the cache is older than five minutes, and falls back to the last good result on failure.
<?php
// --- Configuration ---
$accessToken = 'YOUR_ACCESS_TOKEN';
$cacheFile = __DIR__ . '/wallsio-cache.json';
$cacheTtl = 300; // 5 minutes, in seconds
// --- Fetch posts from the Walls.io API ---
function fetchPosts($accessToken) {
$fields = 'id,type,comment,external_fullname,userlink,'
. 'post_image_cdn,external_image_cdn,permalink,created_timestamp';
$url = 'https://api.walls.io/v1/posts?' . http_build_query([
'access_token' => $accessToken,
'fields' => $fields,
'limit' => 24,
'sort' => '-created_timestamp,-id',
]);
$json = @file_get_contents($url);
if ($json === false) {
return null;
}
$data = json_decode($json, true);
return isset($data['data']) ? $data['data'] : null;
}
// --- Return cached posts, refreshing when stale ---
function getPosts($accessToken, $cacheFile, $cacheTtl) {
if (file_exists($cacheFile) && (time() - filemtime($cacheFile)) < $cacheTtl) {
return json_decode(file_get_contents($cacheFile), true); // still fresh
}
$posts = fetchPosts($accessToken);
if ($posts !== null) {
file_put_contents($cacheFile, json_encode($posts));
return $posts;
}
// Request failed: fall back to a stale cache if we have one
if (file_exists($cacheFile)) {
return json_decode(file_get_contents($cacheFile), true);
}
return [];
}
$posts = getPosts($accessToken, $cacheFile, $cacheTtl);
?>
<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"><title>Our Social Wall</title></head>
<body>
<h1>What people are saying</h1>
<div class="wall">
<?php foreach ($posts as $post): ?>
<article>
<p><strong><?= htmlspecialchars($post['external_fullname'] ?? 'Unknown') ?></strong></p>
<?php $img = $post['post_image_cdn'] ?? $post['external_image_cdn'] ?? null; ?>
<?php if ($img): ?>
<img src="<?= htmlspecialchars($img) ?>" alt="" width="300">
<?php endif; ?>
<p><?= nl2br(htmlspecialchars($post['comment'] ?? '')) ?></p>
<p><a href="<?= htmlspecialchars($post['permalink'] ?? '#') ?>">View original post</a></p>
</article>
<?php endforeach; ?>
</div>
</body>
</html>JavaScript (Node.js)
Since the token has to stay server-side, this is a small Node.js server (Node 18+ for the built-in fetch). Install Express with npm install express, save it as server.js, run node server.js. It caches posts in memory for five minutes.
// server.js - run with: node server.js
const express = require('express');
const app = express();
const PORT = 3000;
const ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN';
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes, in milliseconds
let cache = { posts: [], fetchedAt: 0 };
async function fetchPosts() {
const fields = 'id,type,comment,external_fullname,userlink,' +
'post_image_cdn,external_image_cdn,permalink,created_timestamp';
const url = 'https://api.walls.io/v1/posts?' + new URLSearchParams({
access_token: ACCESS_TOKEN,
fields: fields,
limit: '24',
sort: '-created_timestamp,-id',
});
const res = await fetch(url);
if (!res.ok) throw new Error('Walls.io API error: ' + res.status);
const body = await res.json();
return body.data || [];
}
async function getPosts() {
const now = Date.now();
if (now - cache.fetchedAt < CACHE_TTL && cache.posts.length) {
return cache.posts; // still fresh
}
try {
const posts = await fetchPosts();
cache = { posts, fetchedAt: now };
return posts;
} catch (err) {
console.error(err);
return cache.posts; // fall back to the last good result
}
}
function escapeHtml(str = '') {
return str.replace(/[&<>"']/g, (c) => (
{ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }[c]
));
}
function renderPost(post) {
const image = post.post_image_cdn || post.external_image_cdn;
return `
<article>
<p><strong>${escapeHtml(post.external_fullname || 'Unknown')}</strong></p>
${image ? `<img src="${escapeHtml(image)}" alt="" width="300">` : ''}
<p>${escapeHtml(post.comment || '')}</p>
<p><a href="${escapeHtml(post.permalink || '#')}">View original post</a></p>
</article>`;
}
app.get('/', async (req, res) => {
const posts = await getPosts();
res.send(`
<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"><title>Our Social Wall</title></head>
<body>
<h1>What people are saying</h1>
<div class="wall">${posts.map(renderPost).join('')}</div>
</body>
</html>`);
});
app.listen(PORT, () => console.log(`Social wall running on http://localhost:${PORT}`));What prompt should you give your AI coding agent?
Here is the useful part. One well-structured prompt covers every agent on the market. Paste it into whichever tool you use, switch the language line to JavaScript if you prefer, and read the tool notes below.
I want to build a social wall - a single web page that displays a live
feed of social media posts aggregated by Walls.io. Please read the
official API documentation first so your code matches the real
endpoints and field names:
https://github.com/DieSocialisten/Walls.io-API-Docs
The wall should pull its content from the Walls.io GET /posts endpoint
(base URL https://api.walls.io/v1) using my access token.
Please build it with these requirements:
Tech and structure
- Language: PHP, delivered as a single self-contained index.php file.
- Read the access token from an environment variable
(e.g. WALLSIO_ACCESS_TOKEN). Never hard-code the token in the source.
Fetching data
- Call GET /posts and request only the fields the frontend needs:
id, type, comment, external_fullname, userlink, post_image_cdn,
external_image_cdn, permalink and created_timestamp.
- Fetch the latest 24 posts and sort them by -created_timestamp so the
newest posts appear first (the API's default -id order reflects when
posts arrived at Walls.io, not when they were posted, so do not rely
on it for display order).
Caching and resilience
- Cache the API response to a local JSON file. Only call the API again
when the cache is older than 5 minutes; otherwise serve the cache.
This keeps us comfortably within the API rate limit.
- If an API request fails, fall back to the last successfully cached
response so the wall never renders blank. If there is no cache at
all, degrade gracefully to an empty state.
Rendering
- Render a clean, readable feed. For each post show: the author
(external_fullname), the post image (post_image_cdn, falling back to
external_image_cdn when it is missing, and no image element at all if
neither exists), the text (comment), and a link to the original post
(permalink).
- Escape all output to prevent XSS.
- Keep the markup simple and semantic; I will add my own CSS later.
Security note
- The Walls.io API does not support CORS and the access token must stay
private, so make sure all API calls happen server-side, never in the
browser.
When you are done, add short comments explaining each part and tell me
exactly how to set the environment variable and run the page locally.There are three habits that make this land useful no matter what tool you use. Give the agent the link to the docs so it uses the real field names. Explain the limitations, because the five-minute cache, the server-side rule, and the environment-variable token are what make a demo different from something you would ship. Then, make small changes, like “add a masonry grid” or “swap the file cache for Redis.”
Which coding agent should you use?
Any of them will build this. The differences are mostly in how you invoke the tool, not in what you ask it. Here is what to know for each.
Claude Code (CLI and desktop app)
Claude Code is Anthropic’s agentic tool. It runs in your terminal (type claude in your project folder) and also ships as a desktop app. It reads project context from a CLAUDE.md file, supports MCP servers, and asks before it edits files or runs commands. Drop the docs URL and your conventions into CLAUDE.md so every prompt starts with context, use plan mode to review the approach first, and let it run the project so it can fix its own errors from real output.
Save this as CLAUDE.md in your project root:
# Walls.io social wall - project context
Data source: GET https://api.walls.io/v1/posts
Docs: https://github.com/DieSocialisten/Walls.io-API-Docs
Rules for all code in this project:
- Read the access token from the WALLSIO_ACCESS_TOKEN env var. Never hard-code it.
- All Walls.io API calls run server-side. The API has no CORS, so never call it from the browser.
- Request only the fields the frontend needs and sort by -created_timestamp (not the default -id order).
- Cache API responses for 5 minutes; serve the last good cache if a request fails.
- Escape all output to prevent XSS.Cursor
Cursor is an AI-first editor built on VS Code. Its Agent mode creates and edits files across the project, runs commands, and reads docs. Add a .cursor/rules file with your stack and the server-side rule so it holds on every edit, point it at the API reference with the @Docs feature or a pasted URL, then run the prompt in Agent mode and accept the diffs.
Save this as .cursor/rules/wallsio.mdc:
---
description: Walls.io social wall - project rules
alwaysApply: true
---
- Data source: GET https://api.walls.io/v1/posts
(docs: https://github.com/DieSocialisten/Walls.io-API-Docs).
- Read the access token from WALLSIO_ACCESS_TOKEN; never hard-code it.
- All Walls.io API calls run server-side. The API has no CORS; never call it from the browser.
- Sort posts by -created_timestamp, not the default -id order.
- Cache responses for 5 minutes and fall back to the last good cache on failure.
- Escape all output to prevent XSS.OpenAI Codex
OpenAI Codex is a set of surfaces sharing one model: a terminal CLI (codex), an IDE extension for VS Code, Cursor and Windsurf, a desktop app (codex app), and a cloud agent at chatgpt.com/codex. It reads an AGENTS.md file, supports MCP, and has approval modes that control how much it does on its own. In the CLI, start in the default suggest mode and review each diff before approving. For a hands-off build, hand the same prompt to the cloud agent and apply the changes when it finishes.
Save this as AGENTS.md in your project root:
# Walls.io social wall
Data source: GET https://api.walls.io/v1/posts
Docs: https://github.com/DieSocialisten/Walls.io-API-Docs
Conventions:
- Read the access token from WALLSIO_ACCESS_TOKEN. Never hard-code it.
- All Walls.io API calls run server-side. The API has no CORS, so never call it from the browser.
- Sort posts by -created_timestamp (not the default -id order).
- Cache responses for 5 minutes; serve the last good cache if a request fails.
- Escape all output to prevent XSS.ChatGPT (GPT in the browser)
If you don’t want to use an agent on your machine, plain ChatGPT works too. It won’t modify your filesystem, so you’ll need to generate the files and paste them in yourself. Turn on web browsing so it can read the docs, ask for “the complete index.php file, ready to paste,” and when something breaks, paste the exact error back and let it revise. It is the most manual route and the one that needs no setup.
Paste this at the start of your chat (or into Custom Instructions):
Follow these rules for all code in this chat:
- We are building a Walls.io social wall using GET https://api.walls.io/v1/posts.
Docs: https://github.com/DieSocialisten/Walls.io-API-Docs
- Read the access token from an env var (WALLSIO_ACCESS_TOKEN); never hard-code it.
- All API calls run server-side. The API has no CORS, so never call it from the browser.
- Sort posts by -created_timestamp, not the default -id order.
- Cache responses for 5 minutes; serve the last good cache if a request fails.
- Escape all output to prevent XSS.
- Always give me complete, ready-to-paste files.Grok Build
Grok Build is xAI’s terminal coding agent, available to SuperGrok and X Premium+ subscribers. Install it with curl -fsSL https://x.ai/cli/install.sh | bash. It has a plan-first workflow, can run subagents in parallel, reads AGENTS.md (and CLAUDE.md) for context, and supports MCP. Start in plan mode, review or edit the plan, then let it build, with every change shown as a clean diff. This task is small, so skip the parallel subagents and keep the scope tight.
Save this as AGENTS.md in your project root:
# Walls.io social wall
Data source: GET https://api.walls.io/v1/posts
Docs: https://github.com/DieSocialisten/Walls.io-API-Docs
Rules:
- Read the access token from WALLSIO_ACCESS_TOKEN. Never hard-code it.
- All Walls.io API calls run server-side. The API has no CORS, so never call it from the browser.
- Sort posts by -created_timestamp (not the default -id order).
- Cache responses for 5 minutes; serve the last good cache if a request fails.
- Escape all output to prevent XSS.
- This is a small task: no parallel subagents needed.GitHub Copilot
GitHub Copilot It has an agent mode in VS Code that plans a task, edits multiple files, and runs commands. It also has a coding agent that you can assign to a GitHub issue. This agent will open a pull request for you. In VS Code, switch Copilot Chat to Agent mode, paste the prompt, and approve the changes. For an asynchronous workflow, write the requirements into a GitHub issue, assign it to Copilot, and review the pull request it opens.
Save this as .github/copilot-instructions.md:
# Walls.io social wall
Data source: GET https://api.walls.io/v1/posts
Docs: https://github.com/DieSocialisten/Walls.io-API-Docs
When writing code for this repo:
- Read the access token from WALLSIO_ACCESS_TOKEN. Never hard-code it.
- All Walls.io API calls run server-side. The API has no CORS, so never call it from the browser.
- Sort posts by -created_timestamp (not the default -id order).
- Cache responses for 5 minutes; serve the last good cache if a request fails.
- Escape all output to prevent XSS.Google Antigravity
Google Antigravity is Google’s agent-first platform, which replaced Gemini CLI for consumers in mid-2026. It comes as the Antigravity 2.0 desktop app and a terminal tool, the Antigravity CLI (invoked with agy), both sharing one agent backend. It uses a GEMINI.md file and an .agents/ folder for context and subagents. In the desktop app, use the plan-first Manager surface to approve the approach before code is written. In the terminal, run the same prompt through agy.
Save this as GEMINI.md in your project root:
# Walls.io social wall
Data source: GET https://api.walls.io/v1/posts
Docs: https://github.com/DieSocialisten/Walls.io-API-Docs
Project rules:
- Read the access token from WALLSIO_ACCESS_TOKEN. Never hard-code it.
- All Walls.io API calls run server-side. The API has no CORS, so never call it from the browser.
- Sort posts by -created_timestamp (not the default -id order).
- Cache responses for 5 minutes; serve the last good cache if a request fails.
- Escape all output to prevent XSS.Others worth a look
Windsurf (formerly Codeium) is an agentic IDE – use its Cascade agent in write mode. Devin is an autonomous cloud agent for fully hands-off delegation. Cline and Aider are open-source agents, a VS Code extension and a terminal tool, that let you bring your own model. All of them take the same universal prompt.
Each reads its own rules file. Drop the same context into whichever one applies:
Windsurf -> .windsurf/rules/wallsio.md
Cline -> .clinerules
Aider -> CONVENTIONS.md (pass with: aider --read CONVENTIONS.md)
Devin -> paste the rules into the task description
# Same rules in every case:
# - Token from WALLSIO_ACCESS_TOKEN; never hard-code it.
# - All API calls server-side (the API has no CORS).
# - Sort by -created_timestamp, not the default -id.
# - Cache 5 minutes; serve the last good cache on failure.
# - Escape all output to prevent XSS.
# Docs: https://github.com/DieSocialisten/Walls.io-API-Docs
Frequently asked questions
Do I need a paid plan to use the Walls.io API?
Yes. API access is included with all paid Walls.io plans. You can find it in your wall settings, under the API section. This section generates the token that’s needed for each request. You can try it for free first to see if it’s right for you.
Can I call the Walls.io API directly from the browser?
No. The API doesn’t support CORS. If you make a client-side call, anyone who opens dev tools will be able to see your access token. Keep the call on the server, or run a thin proxy of your own that holds the token and forwards the request.
How often should I refresh the feed?
About every five minutes is a sensible default. It keeps the wall current without hammering the API, and it sits well inside the rate limit, where one to two requests per second is fine. If the walls are busy, make them shorter. If the walls are quiet, make them longer.
Why are the posts showing in the wrong order?
The default order follows when posts reached Walls.io, not when they were posted, which can look scrambled after you add a new source. Add sort=-created_timestamp to your request and the newest content comes first.
It shows the networks that Walls.io supports in one standard format, which is the point of the collection. It also doesn’t include data from networks that don’t allow redistributing API content, so a specific platform might be unavailable in some cases. The sources page lists what is currently supported.
Build your wall
The API gives you one integration to maintain and complete freedom over how the content looks. The trade-off is simple: it needs a paid plan, you depend on a third party for uptime, and you’re responsible for the caching and fallback, so even a brief hiccup won’t blank the screen. That’s a good deal for most event, website, and signage projects.
Grab a token, paste the prompt into your agent of choice, and you can have a working wall today. Start your free trial and point your agent at the API docs.