Base URL: https://api.fedica.com/v1
The Platform value returned by the accounts endpoints is one of these names.
All endpoints return a consistent error response format. Always check the Success field: validation errors (a missing parameter, an account or report that isn't found, and so on) are returned with HTTP status 200 and "Success": false.
{
"Success": false,
"Error": "Error message describing what went wrong"
}HTTP Status Codes:
Success and Error for the outcomeBase path: /api/accounts
Retrieve the social media accounts connected to your Fedica account. The Id of each account is the accountId used by the publishing, analytics and research endpoints.
No parameters required.
{
"Success": true,
"Error": null,
"Accounts": [
{
"Platform": "Twitter",
"Username": "fedica",
"Id": "1-12345"
}
]
}Platform: Platform name, one of the supported platforms
Username: The account's username on the platform
Id: Account identifier to use as accountId in other endpoints
Base path: /api/publish
Publish a post now, schedule it for a later date, add it to a pipeline, or let a posting schedule pick the time on a given day, on one or multiple social media accounts.
{
"PipelineId": 123,
"DateTime": "2026-10-01T12:00:00Z",
"Posts": [
{
"AccountIds": ["1-12345", "2-67890"],
"Messages": ["Your post content here"],
"MediaId": ["media-id-1", "media-id-2"],
"MediaLibraryMediaId": ["media-library-id"]
}
]
}Id
Type: string (optional)
Used for editing existing posts. Do not provide when creating new posts.
PipelineId
Type: integer (optional)
The ID of a pre-configured publishing pipeline (see /publish/pipelines). When provided, the post is added to the pipeline and published according to its schedule, and DateTime is ignored. Cannot be combined with ScheduleId.
DateTime
Type: string (optional)
The date and time when the post should be published, in ISO 8601 format with timezone information (e.g., "2026-10-01T12:00:00Z"). It cannot be in the past. If none of DateTime, PipelineId and ScheduleId is provided, the post is published immediately. Ignored when PipelineId is set.
ScheduleId
Type: integer (optional)
The ID of one of your posting schedules (see /publish/schedules). The schedule picks the publishing time within the day of DateTime, in your account's timezone: only the date part of DateTime is used (e.g., "2026-10-01"), and without DateTime the day is today. Cannot be combined with PipelineId.
Posts *
Type: array of Post objects
Array of post configurations. Each post can target different accounts and contain different content. If the same post goes to multiple accounts, use only one post object; if you wish to customize the post for different platforms, use a separate post object per platform.
AccountIds *
Type: array of strings
The Id of each account where this post will be published, as returned by /accounts/list.
Messages *
Type: array of strings
Array of message content strings. Multiple messages can be provided for platforms that support threads.
Title
Type: string (optional)
Title of the post, for platforms that have one:
ChannelId
Type: string (required for Pinterest)
The board (Pinterest), blog (Tumblr) or channel (PeerTube) to post to: the Id of one of the account's channels from /publish/channels. Required for Pinterest. Optional for Tumblr, which otherwise posts to the account's main blog, and PeerTube, which otherwise posts to the account's first channel. Channels belong to one account, so use a separate post object for each of these accounts.
Visibility
Type: string (optional)
Who can see the post: Everyone, Followers, Friends, Private, Unlisted or Internal, as far as the platform supports them. Not used by TikTok, whose posts are always public.
Story
Type: boolean (optional)
Posts to Instagram as a story. Only allowed when every account of the post object is an Instagram account.
FirstComment
Type: string (optional)
A comment posted under the post right after it is published, on platforms that support it.
AllowComments, AllowDuet, AllowStitch
Type: boolean (required for TikTok)
Whether viewers can comment on, duet and stitch the post.
CommercialContent
Type: boolean (required for TikTok)
Whether the post promotes a brand, product or service. When true, CommercialContentBrandOwn (promotes your own brand) and CommercialContentBrandOther (promotes a third party) are required, and at least one of them must be true.
StopAutoMusic
Type: boolean (optional, default: false)
TikTok photo posts: when true, TikTok doesn't add music to the post automatically. Ignored by other posts.
AiGeneratedContent
Type: boolean (optional, default: false)
Labels the post as AI-generated content on the platforms that support it:
Ignored by all other platforms.
MediaId
Type: array of strings (default: empty array)
Array of media file IDs obtained from the media upload endpoints. Attach images, videos, or other media to your post.
MediaLibraryMediaId
Type: array of strings (default: empty array)
Array of MediaId values from /publish/media/library. Attaches images and videos already saved in your media library, without uploading them again. They are attached after the MediaId items.
Accounts legacy
Type: array of objects with Platform and AccountId (username)
Kept for backward compatibility and used only when AccountIds is not provided. New integrations should use AccountIds.
{
"Success": true,
"Error": null,
"Id": "12345"
}Success: Boolean indicating if the operation was successful
Error: Error message if operation failed, null otherwise
Id: Content ID of the scheduled post. When a post is saved but publishing it immediately fails, Success is false and Id is still returned.
Retrieve the posts waiting to be published, earliest first, one page at a time.
page
Type: integer (optional, default: 1)
1-based page number.
pageSize
Type: integer (optional, default: 20)
Number of posts per page, between 1 and 100.
{
"Success": true,
"Error": null,
"Count": 42,
"Page": 1,
"PageSize": 20,
"Posts": [
{
"Id": "12345",
"PipelineId": null,
"DateTime": "2026-10-01T12:00:00Z",
"Posts": [
{
"AccountIds": ["1-12345"],
"Messages": ["Your post content here"],
"MediaId": ["stored-media-id"]
}
]
}
]
}Count: Total number of pending posts, across all pages
Page / PageSize: The page returned and its size
Posts: Pending posts in the same shape as the /publish/post request, with DateTime in UTC. MediaId holds the IDs of the media stored with the post, which are not upload file IDs and can't be reused in a new post.
Save a post as a draft without publishing or scheduling it, or edit an existing draft. Drafts can be finished and scheduled later in Fedica or with /publish/post.
{
"Id": null,
"Posts": [
{
"AccountIds": ["1-12345", "2-67890"],
"Messages": ["Your post content here"],
"MediaId": ["media-id-1"]
}
]
}Id
Type: string (optional)
The ID of a draft, or of a post that has not been sent yet, to replace with this draft. Leave empty to create a new draft.
{
"Success": true,
"Error": null,
"Id": "12345"
}Id: The draft's ID. Pass it as Id to edit the draft, or to /publish/post to schedule it.
Retrieve your drafts, most recently edited first, one page at a time.
page
Type: integer (optional, default: 1)
1-based page number.
pageSize
Type: integer (optional, default: 20)
Number of drafts per page, between 1 and 100.
{
"Success": true,
"Error": null,
"Count": 5,
"Page": 1,
"PageSize": 20,
"Posts": [
{
"Id": "12345",
"Posts": [
{
"AccountIds": ["1-12345"],
"Messages": ["Your draft content here"],
"MediaId": ["stored-media-id"]
}
]
}
]
}Count: Total number of drafts, across all pages
Page / PageSize: The page returned and its size
Posts: Drafts in the same shape as the /publish/draft request. As with pending posts, MediaId holds the IDs of the media stored with the draft, which are not upload file IDs and can't be reused in a new post.
Retrieve a list of available publishing pipelines.
No parameters required.
{
"Success": true,
"Error": null,
"Pipelines": [
{
"Id": "123",
"Name": "Marketing Pipeline"
}
]
}Pipelines: Array of pipeline objects with Id and Name properties. Use the Id as PipelineId in /publish/post.
Retrieve a list of your posting schedules.
No parameters required.
{
"Success": true,
"Error": null,
"Schedules": [
{
"Id": "456",
"Name": "Weekday Mornings"
}
]
}Schedules: Array of schedule objects with Id and Name properties. Use the Id as ScheduleId in /publish/post.
Retrieve the boards, blogs and channels your Pinterest, Tumblr and PeerTube accounts can post to.
No parameters required.
{
"Success": true,
"Error": null,
"Accounts": [
{
"AccountId": "5-12345",
"Platform": "Pinterest",
"Username": "yourbrand",
"Channels": [
{
"Id": "987654321",
"Name": "Product Ideas"
}
]
}
]
}Accounts: Your Pinterest, Tumblr and PeerTube accounts, each with the Pinterest boards, Tumblr blogs or PeerTube channels it can post to. Use a channel's Id as ChannelId in a post object for that account in /publish/post: required for Pinterest, optional for Tumblr and PeerTube.
Retrieve a list of connected social media accounts. This endpoint is kept for backward compatibility; use /accounts/list, which also returns the account Id.
No parameters required.
{
"Success": true,
"Error": null,
"Accounts": [
{
"Platform": "Twitter",
"AccountId": "fedica"
}
]
}Accounts: Array of connected account objects with Platform and AccountId (the account's username) properties
Initialize a media upload session. Call this endpoint before uploading media chunks.
No request body required.
{
"Success": true,
"Error": null,
"Id": "file-abc123"
}Id: File ID to use for subsequent upload and finalize operations
Upload a chunk of media data. For large files, split the file into chunks and call this endpoint multiple times.
Content-Type: multipart/form-data
chunkIndex: 0
fileId: file-abc123
file: [binary data]Alternatively, this endpoint accepts a JSON object with the file data in base64:
{
"chunkIndex": 0,
"fileId": "file-abc123",
"file": "base64-encoded-data"
}chunkIndex *
Type: integer
Zero-based index of the current chunk. Start with 0 for the first chunk and increment for each subsequent chunk.
fileId *
Type: string
File ID obtained from the /publish/media/init endpoint. This associates the chunk with the upload session.
file *
Type: binary (form data) or string (JSON)
The file chunk: binary data when sent as form data, or base64-encoded when sent as JSON.
{
"Success": true,
"Error": null
}Complete the media upload process and provide metadata about the uploaded file. To use a file that is already online, skip the chunk upload and pass its url here instead.
{
"fileId": "file-abc123",
"metadata": {
"altText": "Description for accessibility",
"mimeType": "image/jpeg",
"fileName": "photo.jpg",
"size": 1048576,
"width": 1920,
"height": 1080,
"aspectRatio": 1.777,
"duration": 30.5,
"frameRate": 30.0,
"bitRate": 5000000.0
}
}fileId *
Type: string
File ID from the initialization step.
url
Type: string (optional)
Public http or https URL of the image or video, used instead of uploading chunks. It must be a direct link to the file, not a page that shows it. Files up to 1GB. When set, metadata.mimeType, width and height are required, plus duration for a video, and size is taken from the downloaded file.
metadata *
Type: MediaMetaData object
Comprehensive metadata about the uploaded media file.
altText *
Type: string
Alternative text description for accessibility. Describes the content of images or videos for screen readers.
mimeType *
Type: string
MIME type of the file (e.g., "image/jpeg", "video/mp4", "image/png").
fileName *
Type: string
Original filename of the uploaded media.
size *
Type: long (integer)
File size in bytes.
width
Type: integer (optional)
Width in pixels (for images and videos).
height
Type: integer (optional)
Height in pixels (for images and videos).
aspectRatio
Type: double (optional)
Aspect ratio calculated as width/height (e.g., 1.777 for 16:9).
duration
Type: double (optional)
Duration in seconds (for video and audio files).
frameRate
Type: double (optional)
Video frame rate in frames per second (e.g., 30.0, 60.0).
bitRate
Type: double (optional)
Bitrate in bits per second (for video and audio files).
{
"Success": true,
"Error": null
}Retrieve the images and videos saved in your media library, newest first, one page at a time, optionally filtered.
page
Type: integer (optional, default: 1)
1-based page number.
pageSize
Type: integer (optional, default: 20)
Number of items per page, between 1 and 100.
label
Type: string (optional)
Only items with this label, by the label's name as shown in the media library.
name
Type: string (optional)
Only items whose name contains this text.
altText
Type: string (optional)
Only items whose alt text contains this text.
type
Type: string (optional)
image for images only, or video for videos only.
{
"Success": true,
"Error": null,
"Count": 42,
"Page": 1,
"PageSize": 20,
"Items": [
{
"MediaId": "media-library-id",
"Name": "Product launch banner",
"AltText": "Our new product on a blue background",
"Url": "https://api.fedica.com/v1/medialibrary/item/media-library-id"
}
]
}Count: Total number of items matching the filters, across all pages
Page / PageSize: The page returned and its size
MediaId: Pass it in a post's MediaLibraryMediaId in /publish/post or /publish/draft to attach the item.
Url: Opens the file in Fedica for the account owner while signed in; it is not a public link.
Initialize Upload
Call POST /publish/media/init to get a file ID
Upload Chunks
Call POST /publish/media/upload for each chunk of your file, or skip this step and pass the file's url when you finalize
Finalize Upload
Call POST /publish/media/finalize with metadata
Schedule Post
Use the file ID in MediaId of POST /publish/post to publish
Base path: /api/analytics
Analytics for one of your own connected accounts. Every endpoint takes the accountId query parameter: the Id of the account from /accounts/list. If the account isn't found, the error is "Account not found"; if Fedica has no data for the account yet, the error is "This capability is not available for this account".
Key metrics for the account: follower quality, activity, follower and following counts, new followers and unfollows, and the best and least performing country and city.
accountId *
Type: string
Account Id from /accounts/list.
{
"Success": true,
"Error": null,
"overview": {
"quality": 82,
"activity_score": 64,
"followers": 15230,
"following": 870,
"new": 312,
"unfollows": 45,
"best_country": "United States",
"least_country": "Canada",
"best_city": "New York",
"least_city": "Toronto"
}
}quality: Follower quality score (0-100), null when not available
activity_score: Follower activity score, null when not available
followers / following: Current follower and following counts
new / unfollows: New followers and unfollows over the most recent period (your email digest period, 7 days by default)
best_country / least_country, best_city / least_city: Locations with the most and least follower growth over the same period
Demographics and distributions of the account's followers.
accountId *
Type: string
Account Id from /accounts/list.
{
"Success": true,
"Error": null,
"audience": {
"languages": [{ "Name": "English", "Count": 9800 }],
"timezones": [{ "Name": "Eastern Time", "Count": 4100 }],
"gender": {
"ErrorMessage": null,
"Items": [{ "Name": "Male", "Count": 6200 }, { "Name": "Female", "Count": 5400 }]
},
"occupation": [{ "Name": "Marketing", "Count": 1200 }],
"age": {
"ErrorMessage": null,
"Items": [{ "Name": "25-34", "Count": 4300 }]
},
"follower_distribution": [...],
"follower_tweets": [...],
"follower_activity": [...],
"follower_account_age": [...],
"follower_quality": [...]
}
}Each list is an array of { "Name", "Count" } items. gender and age are groups with Items and an ErrorMessage explaining when the data isn't available.
languages, timezones, occupation: Followers by language, timezone and occupation
follower_distribution: Followers by their own follower count
follower_tweets: Followers by the number of posts they have made
follower_activity: Followers by how recently they were active
follower_account_age: Followers by account age
follower_quality: Followers by quality category
Counts over time for the account. All four endpoints take the same parameters and return the same response shape.
/analytics/follower_history - follower count over time/analytics/follower_changes - change in followers from one data point to the next/analytics/following_history - following count over time/analytics/post_history - post count over timeaccountId *
Type: string
Account Id from /accounts/list.
{
"Success": true,
"Error": null,
"Title": "Followers",
"Labels": ["Followers"],
"Points": [
{ "Label": "2026-09-01", "Values": [15010] },
{ "Label": "2026-09-02", "Values": [15042] }
]
}Title: Chart title
Labels: Name of each series
Points: One data point per date; Values holds one value per series, in the order of Labels
When the account's audience is most likely to see and engage with a post. Returns the error "Account does not support best_time_to_post" for platforms without this feature. When there's no data yet, only Success is returned.
accountId *
Type: string
Account Id from /accounts/list.
{
"Success": true,
"Error": null,
"BestTime": [
[{ "Name": "0", "Count": 12 }, { "Name": "1", "Count": 8 }, ...],
...
],
"BestTimeSegmented": {
"Americas": [[...], ...],
"Europe & Middle East": [[...], ...],
"Asia & Australia": [[...], ...]
},
"ColumnNames": ["ID", "Time of the day", "Day of the week", "", "Reach"],
"DayIndex": 3,
"BestHourToday": "2 PM",
"BestHourThisWeek": "Tuesday 3 PM",
"BestDay": "Tuesday",
"Tz": "UTC"
}BestTime: 7 arrays, one per day of the week starting with Sunday, each holding the audience reach for each hour of the day
BestTimeSegmented: The same grid for each audience region, when available
ColumnNames: Column titles for charting the grid
DayIndex: Index of today in BestTime (0 = Sunday)
BestHourToday, BestHourThisWeek, BestDay: The best hour today, best hour this week and best day to post
Tz: Timezone of the times returned
Interactions, impressions, engagement rates and top posts for a date range, compared with the previous period of the same length. Returns the error "Account does not support engagements" for platforms without post analytics.
accountId *
Type: string
Account Id from /accounts/list.
startDate *
Type: date (e.g., 2026-09-01)
First day of the range. Must not be after endDate.
endDate *
Type: date (e.g., 2026-09-30)
Last day of the range, inclusive.
curl "https://api.fedica.com/v1/analytics/engagements?accountId=1-12345&startDate=2026-09-01&endDate=2026-09-30" \
-H "Authorization: Bearer YOUR_API_TOKEN"{
"Success": true,
"Error": null,
"TotalEngagements": "1.2K",
"TotalCounts": 1240,
"TotalImpressions": 58000,
"TotalPosts": 30,
"DeltaCount": 180,
"PrevCount": 1060,
"PrevPosts": 27,
"PrevImpressions": 51000,
"Interactions": [{ "Name": "Likes", "Count": 900 }, ...],
"Impressions": [{ "Name": "2026-09-01", "Count": 1800 }, ...],
"Posts": [{ "Name": "2026-09-01", "Count": 1 }, ...],
"Rates": [{ "Name": "Engagement rate", "Count": 2 }, ...],
"LastInteractions": [...],
"TopInteractions": [
{
"Id": "1839201",
"Text": "Your top post",
"Retweets": 40,
"Replies": 12,
"Favorites": 210,
"QuoteTweets": 3,
"Impressions": 9100,
"TotalEngagements": 265
}
],
"NoInteractionsMessage": null,
"DataDateMessage": null
}TotalEngagements: Total engagements, formatted for display
TotalCounts, TotalImpressions, TotalPosts: Totals for the requested range
PrevCount, PrevImpressions, PrevPosts: Totals for the previous period of the same length
DeltaCount: Change in engagements compared with the previous period
Interactions, Impressions, Posts, Rates, LastInteractions: Breakdowns as { "Name", "Count" } items
TopInteractions: The posts with the most engagement in the range
NoInteractionsMessage, DataDateMessage: Informational messages, e.g. when there are no interactions or about how recent the data is
Base path: /api/research
Access the research reports you've created in Fedica. Each report type has a list endpoint, which returns the reports created from one of your accounts, and a get endpoint, which returns a report's results by its id. A report must have the status Complete before its results can be retrieved; otherwise the error is "Report is not complete".
List the reports of one type created from an account. All four endpoints take the same parameters and return the same response shape.
/research/analyze/reports - analyze reports on third-party accounts/research/compare/reports - follower overlap between accounts/research/audit/reports - follower quality audits/research/search/reports - keyword and hashtag searchesaccountId *
Type: string
Account Id from /accounts/list; only reports created from this account are returned.
{
"Success": true,
"Error": null,
"Reports": [
{
"Id": 98765,
"Name": "competitor",
"Status": "Complete"
}
]
}Id: Report id, used by the matching get endpoint
Name: Report name
Status: Complete, Inprogress or Error
The overview and audience analytics of the account an analyze report is about, in the same shape as /analytics/overview and /analytics/audience.
id *
Type: integer
Report id from /research/analyze/reports.
{
"Success": true,
"Error": null,
"overview": { "quality": 75, "followers": 48200, ... },
"audience": { "languages": [...], "gender": {...}, ... }
}The follower overlap between the accounts in a compare report. One result is returned for each pair of accounts; when the report compares more than two accounts, the first result is the overlap across all of them.
id *
Type: integer
Report id from /research/compare/reports.
{
"Success": true,
"Error": null,
"Models": [
{
"UserIds": ["111", "222"],
"UserNames": ["fedica", "competitor"],
"Totals": [15230, 48200],
"IntersectionCount": 3100,
"IntersectionCountShort": "3.1K",
"Title": "Common followers",
"Lines": ["..."],
"CommonLine": [{ "Id": "111", "Text": "fedica", "Count": 3100 }],
"Data": [
{ "Sets": ["111"], "Size": 15230 },
{ "Sets": ["222"], "Size": 48200 },
{ "Sets": ["111", "222"], "Size": 3100 }
]
}
]
}UserIds / UserNames / Totals: The accounts compared and their follower counts
IntersectionCount / IntersectionCountShort: Followers the accounts have in common, as a number and formatted for display
Title, Lines, CommonLine: Summary text of the comparison
Data: Set sizes for drawing a Venn diagram
The follower quality breakdown and final score of an audit report.
id *
Type: integer
Report id from /research/audit/reports.
{
"Success": true,
"Error": null,
"Categories": [
{ "Name": "Real", "Count": 12100 },
{ "Name": "Inactive", "Count": 2300 },
...
],
"Total": 15230,
"FinalScore": {
"Score": 82,
"Label": "Good"
}
}Categories: Followers in each quality category
Total: Total followers audited
FinalScore: Overall quality score and its label
The results of a keyword or hashtag search report: who is posting, their demographics and activity over time.
id *
Type: integer
Report id from /research/search/reports.
{
"Success": true,
"Error": null,
"Languages": [{ "Name": "English", "Count": 820 }],
"Genders": [...],
"Occupations": [...],
"Age": [...],
"TweetsData": [...],
"EngageData": [...],
"DistroData": [...],
"TweetDistro": [...],
"ActivityDistro": [...],
"AccountAgeDistro": [...],
"Interactions": [{ "Name": "Likes", "Count": 5400 }],
"Interval": 1,
"ActivityData": [
{ "Key": "2026-09-01T00:00:00", "Value": 34 },
{ "Key": "2026-09-01T01:00:00", "Value": 41 }
]
}Lists are arrays of { "Name", "Count" } items.
Languages, Genders, Occupations, Age: Demographics of the accounts posting
TweetsData: Matching posts by type: mentions, reposts and original posts
EngageData: Engagement the matching posts received: replies, reposts, likes and quotes
DistroData, TweetDistro, ActivityDistro, AccountAgeDistro: Posting accounts by follower count, post count, recent activity and account age
Interactions: Totals by interaction type
ActivityData: Number of matching posts over time
Interval: Time between ActivityData points: 0 = minute, 1 = hour, 2 = day