Helpchevron_rightAPI Reference

API Reference

Complete documentation for the Socialfire REST API. Use these endpoints to fetch Instagram feed data and integrate it into your applications.

Authentication

The public feed API does not require authentication. All published feeds are publicly accessible via their feed ID or slug.

check_circle

No API keys required - Simply make GET requests to fetch feed data. CORS is enabled for cross-origin requests.

Base URL

https://yourdomain.com

Replace yourdomain.com with your actual Socialfire deployment URL.

GET/api/feeds/:feedId

Get Feed by ID or Slug

Retrieves a feed with all its posts and configuration. Returns cached data for optimal performance.

Path Parameters

Parameter	Type	Description
`feedId`	string	Feed slug (e.g., `my-feed`) or MongoDB ObjectID

Example Request

curl https://yourdomain.com/api/feeds/my-awesome-feed

Example Response

{
  "feedId": "507f1f77bcf86cd799439011",
  "slug": "my-awesome-feed",
  "name": "Homepage Gallery",
  "layout": "GRID",
  "columns": 3,
  "rows": 3,
  "gap": 16,
  "showCaptions": true,
  "showLikes": true,
  "showComments": true,
  "posts": [
    {
      "id": "17842915793354225",
      "caption": "Amazing sunset! #photography",
      "mediaType": "IMAGE",
      "mediaUrl": "https://scontent.cdninstagram.com/...",
      "permalink": "https://www.instagram.com/p/ABC123/",
      "thumbnailUrl": null,
      "timestamp": "2024-01-12T20:30:00+0000",
      "likeCount": 1234,
      "commentsCount": 56
    }
  ],
  "cachedAt": "2024-01-12T20:00:00.000Z",
  "expiresAt": "2024-01-12T21:00:00.000Z"
}

Response Headers

Header	Value
`Content-Type`	application/json
`Cache-Control`	public, max-age=3600, s-maxage=3600
`Access-Control-Allow-Origin`	*

Feed Object

The feed object contains all configuration and posts for an Instagram feed.

Field	Type	Description
`feedId`	string	Unique feed identifier (MongoDB ObjectID)
`slug`	string	Human-readable URL slug
`name`	string	Display name of the feed
`layout`	string	Layout type: GRID, CAROUSEL, or MASONRY
`columns`	number	Number of columns (1-6)
`rows`	number	Number of rows (1-10)
`gap`	number	Space between posts in pixels
`showCaptions`	boolean	Whether to display post captions
`showLikes`	boolean	Whether to display like counts
`showComments`	boolean	Whether to display comment counts
`posts`	Post[]	Array of Instagram posts
`cachedAt`	string	ISO 8601 timestamp when cache was generated
`expiresAt`	string	ISO 8601 timestamp when cache expires

Post Object

Each post represents an Instagram media item with metadata.

Field	Type	Description
`id`	string	Instagram media ID
`caption`	string \| null	Post caption text
`mediaType`	string	IMAGE, VIDEO, or CAROUSEL_ALBUM
`mediaUrl`	string	Direct URL to media file (Instagram CDN)
`permalink`	string	Permanent link to Instagram post
`thumbnailUrl`	string \| null	Thumbnail URL (for videos)
`timestamp`	string	ISO 8601 publish timestamp
`likeCount`	number	Number of likes (optional)
`commentsCount`	number	Number of comments (optional)

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

200OK

Request succeeded, feed data returned

404Not Found

Feed with specified ID or slug does not exist

{
  "error": "Feed not found"
}

500Internal Server Error

Something went wrong on the server

{
  "error": "Internal server error"
}

503Service Unavailable

Instagram API sync failed and no cache available

{
  "error": "Failed to sync feed and no cache available"
}

Rate Limits

The Socialfire API itself has no rate limits. However, Instagram API rate limits apply to feed syncing operations.

info

Best Practice: Since feeds are cached, you can make as many API requests as needed without worrying about Instagram rate limits. The cache automatically refreshes based on your configured TTL (default: 1 hour).

Caching

Socialfire implements intelligent caching to optimize performance and reduce Instagram API calls.

How Caching Works

check_circleFeeds are cached when first accessed or manually refreshed
check_circleCache duration is configurable per feed (default: 3600 seconds / 1 hour)
check_circleExpired cache automatically triggers a background sync
check_circleIf sync fails, stale cache is served with a warning

Cache Headers

The API includes standard HTTP cache headers:

Cache-Control: public, max-age=3600, s-maxage=3600

This allows CDNs and browsers to cache responses, reducing load on your server.

Manual Refresh

To force a feed refresh before cache expires, use the "Refresh" button in the dashboard. This is useful when:

You've just posted new content on Instagram
You want to preview feed changes immediately
Testing feed configuration updates

TypeScript Integration

Type definitions for TypeScript projects:

export interface SocialfirePost {
  id: string;
  caption: string | null;
  mediaType: 'IMAGE' | 'VIDEO' | 'CAROUSEL_ALBUM';
  mediaUrl: string;
  permalink: string;
  thumbnailUrl: string | null;
  timestamp: string;
  likeCount?: number;
  commentsCount?: number;
}

export interface SocialfireFeed {
  feedId: string;
  slug: string;
  name: string;
  layout: 'GRID' | 'CAROUSEL' | 'MASONRY';
  columns: number;
  rows: number;
  gap: number;
  showCaptions: boolean;
  showLikes: boolean;
  showComments: boolean;
  posts: SocialfirePost[];
  cachedAt: string;
  expiresAt: string;
}

Need help integrating?

Check out our guides or reach out for support.

bookView Documentation supportGet Support