Return the details of a single post within a feed

Firstup API (v2)

Beta Notice: This portal is currently in beta. Some functionality, like Try it is temporarily disabled.

API Concepts and Overview

Each API concept can be found in our Docs; we give an overview of each API, the expected behavior and what is possible.

Technical details are found in this reference, but some complex technicalities are further explained in our docs.

Further technical guidance on SCIM patching, pagination and filtering can be found in our docs:

Technical Details

From this page you can download the OpenAPI specification for the Firstup API. This can be imported into tools such as Postman to generate a collection of test queries or converted into an SDK using Swagger Codegen. Alternatively, you can use the try me function in this platform.

Authorization

All API endpoints use the JSON content type and require an auth token. See Authentication and Authorization for more details on token management. The token and content type should be explicitly set in the request headers. For example:

  curl -X GET "https://partner.socialchorus.com/v2/channels" -H "accept: application/json" -H "Authorization: Bearer <ACCESS TOKEN>"

Main API Sections

Firstup Developer Portal

Download OpenAPI description

openapi.json

openapi.yaml

Overview

URL

https://support.firstup.io/hc/en-us

Servers

https://developers.firstup.io/

Content Publishing

The Content Publishing API provides access to content the same way Program Studio does, enabling the creation and updating of articles, links, videos, and images.

Security: Users with a “publisher” or higher role can work with content in this admin-like function. A 403 code is returned for content-related requests to users without a “publisher” or higher role. Permissions are not granular; any authenticated user may read, update, or take action on any existing content. See user roles and access for more guidance.

States: Content is initially created in the “draft” state. It becomes fully visible in feeds when it has passed the “review” state (meaning that it requires review) and is in the “published” state. Content can also pass through “archived” (similar to deleted), “scheduled” (content to be published in the future automatically), “processing” (refers to media that is still being processed or uploaded; like content in the “draft” state, this content does not become “published” until processing has completed), and “processing error” (media or similar objects that fail during the processing phase; this content cannot be transitioned to another state) states.

Sources: Content sources include “submitted” (by users); “Pinterest,”“RSS,”“Facebook,”“Twitter,” and “Instagram” (for content harvested from external sources); “SocialChorus CPCM” (for content that is republished between programs); “studio” (for admin-created content); and “OAuth Client” (for content published via the Partner API or other OAuth client).

For contextual guidance on content publishing, and for use case examples, refer to our Content Publishing Overview page.

Operations

Feeds

The Feeds API provides access to lists of content similar to how a user sees them in the Firstup experience application. Feeds are specific to the authenticated user and a user can only see what the platform gives them access to.

At their core, feeds are built using filters to find the exact topics and type of posts your application wishes to expose to its users. One of the basic filters is the channels.id filter, but there are additional filters like content_type and visibility. There are also preset configurations called named feeds, which uses the name query parameter and are convenient wrappers around a set of filters. These include things like "trending" posts, "following", and "myfeed". The full list of feed names is outlined in the listFeedPosts documentation.

Feeds are paginated, but have no total records as they are an inherently dynamic list of posts.

Actions like liking, bookmarking, and responding to polls can be taken on individual posts in the same way they can be taken on the experience applications.

For contexctual guidance on feeds, and for use examples, refer to our feeds overview page.

Operations

Return a user's feed of posts

Request

Provides a list of posts in the user’s feed. Accepts pagination and filtering parameters.

Security

oauth2_as_a_user

Query

namestring

Use a specific named feed, which is a preset of filters for specific types of feeds. By default, requests return the "myfeed" feed, which includes posts the user can see but may not necessarily be following. Specifying a name not listed here will result in a 400 Bad Request error.

Default "myfeed"

Enum"myfeed""following""resources""trending""icymi""featured""bookmarked""community_images"

searchstring

Find content matching provided keywords. When specified, parameters other than pagination and the topics filter will be ignored.

filter.user_behaviorsArray of strings

Return content posts that users have interacted with in the provided ways. Defaults to all content if left empty.

Items Enum"liked""bookmarked""read""unread"

filter.channels.idArray of integers

Build the feed from the given topics. Provide a list as either array or comma separated list. Returns posts that are published to ANY of the topics. Defaults to all topics.

filter.initiative_tags.idArray of integers

Build the feed from the given initiative tags. Provide a list as either array or comma separated list. Returns posts that are published with ANY of the initiative tags. Defaults to all content.

filter.content_typeArray of strings

Return only content matching the provided types, which can be a single type or a list as either array or comma separated list. Possible values include 'article', 'link', 'note', 'image', and 'video'. Defaults to all types. Including a type not listed here will result in a 400 Bad Request error.

Items Enum"article""link""note""image""video"

filter.visibilitystring

Limit records to the value provided.

Default "any"

Enum"public""private""any"

filter.featuredstring

Limit records to the value provided.

Default "any"

Enumtruefalse"any"

page.sizeinteger(int64)

Return page.size number of records starting at size*number. Default is 1, resulting in the first page being retrieved

page.numberinteger(int64)

Using classical pagination, the page number to return. Default is 1

Bodyapplication/jsonArray [

integer

]

curl -i -X GET \
  'https://developers.firstup.io/v2/feed/posts?name=myfeed&search=string&filter.user_behaviors=liked&filter.channels.id=0&filter.initiative_tags.id=0&filter.content_type=article&filter.visibility=public&filter.featured=true&page.size=0&page.number=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '[
    0
  ]'

Responses

Success

Bodyapplication/json

dataArray of objects(Feeds.Post.Resource)required

data[].idinteger

Unique identifier for this post

Example: 456

data[].uuidstring(uuid)

Example: "8b358e6b-11d4-4e89-bf7f-ec670e3398ed"

data[].versioninteger

The version of the content creation studio used to generate the content.

1 - Legacy Studio
2 - Creator Studio

Enum12

data[].content_typestring

The type of content. One of: article, image, link, note, or video. The content_type can determine how the post should be presented.

Example: "article"

data[].titlestring

The post title. Can also be considered the headline.

Example: "Example Post Title"

data[].summarystring

Short summary of the post.

Example: "Example Post Summary"

data[].bodystring

The body of the post.

Example: "Example post body"

data[].accent_colorstring

The color of the post, currently only applicable to notes.

data[].authorobject(Content.Post.Resource.author)

data[].channelsArray of objects

A list of the topics this post is published to.

data[].engagementobject

data[].updated_atstring(date-time)

When this content was last updated in ISO8601 format and UTC timezone.

Example: "2000-01-01T00:00:00Z"

data[].published_atstring(date-time)

When this content was published in ISO8601 format and UTC timezone.

Example: "2000-01-01T00:00:00Z"

data[].visibilitystring

An indication of the native availability of the post within the Firstup platform. If 'public', the post has a public_link_url and shares of the post should use that url as the canonical url. If 'private', the post requires user authentication to view.

Enum"private""public""any"

Example: "public"

data[].featuredboolean

Whether the post is featured.

Example: true

data[].featured_labelstring

The content's feature label

Example: "Save Pandora!"

data[].permalink_urlstring

The url of the post on the Firstup platform.

Example: "https://onfirstup.com/acme/acmetimes/sc4#contents/456"

data[].shareable_urlstring

The publicly shareable url of the post if it's visibility is public. Private visibility posts will have no shareable_url.

Example: "https://onfirstup.com/acme/acmetimes/sc4#contents/456"

data[].prepopulated_share_messagestring

The auto-generated string used when sharing the post.

Example: "Example Post Title https://onfirstup.com/acme/acmetimes/sc4#contents/456"

data[].appended_hashtagstring

The hashtag configured to be included when sharing the posts. example: #YourBrand

data[].languagestring

The language. For non-translatable posts, this value will be null.

Example: "en"

data[].is_translatableboolean

Whether the content is translatable.

Example: true

data[].is_commentableboolean

Whether the content allows comments.

Example: true

data[].comment_countinteger

The number of comments on the content.

Example: 5

data[].poster_image_urlstring

The url of the primary image used for this post, if one exists.

Example: "https://cdn.example.com/acme/acmetimes/images/abc123"

data[].linksArray of objects

data[].imagesArray of objects(Content.Image.Resource)

data[].videosArray of objects

metaobject

Response

application/json

{
  "data": [
    { … }
  ],
  "meta": {
    "filters": { … },
    "feed_name": "myfeed",
    "pagination": { … }
  }
}

Return the details of a single post within a feed

Request

Provides the data for a single post in a user’s feed. The post must be visible to the user or a 404 Not Found response will be returned.

Security

oauth2_as_a_user

Path

content_idintegerrequired

ID of the detailed post

Query

localestring

locale (for translatable posts)

curl -i -X GET \
  'https://developers.firstup.io/v2/feed/posts/{content_id}?locale=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json

dataobject(Feeds.Post.Resource)

Response

application/json

{
  "data": {
    "id": 456,
    "uuid": "8b358e6b-11d4-4e89-bf7f-ec670e3398ed",
    "version": 1,
    "content_type": "article",
    "title": "Example Post Title",
    "summary": "Example Post Summary",
    "body": "Example post body",
    "accent_color": "string",
    "author": { … },
    "channels": [ … ],
    "engagement": { … },
    "updated_at": "2000-01-01T00:00:00Z",
    "published_at": "2000-01-01T00:00:00Z",
    "visibility": "public",
    "featured": true,
    "featured_label": "Save Pandora!",
    "permalink_url": "https://onfirstup.com/acme/acmetimes/sc4#contents/456",
    "shareable_url": "https://onfirstup.com/acme/acmetimes/sc4#contents/456",
    "prepopulated_share_message": "Example Post Title https://onfirstup.com/acme/acmetimes/sc4#contents/456",
    "appended_hashtag": "string",
    "language": "en",
    "is_translatable": true,
    "is_commentable": true,
    "comment_count": 5,
    "poster_image_url": "https://cdn.example.com/acme/acmetimes/images/abc123",
    "links": [ … ],
    "images": [ … ],
    "videos": [ … ]
  }
}

Return the engagement details of a single post within a feed

Request

Displays the user’s engagements related to a single feed post, including a timestamp for each type of engagement; for example, a liked_at timestamp is present if the user has liked the post and a bookmarked_at is present if the user has bookmarked the post. The post must be visible to the user or a 404 Not Found response will be returned.

Security

oauth2_as_a_user

Path

content_idintegerrequired

ID of the post

curl -i -X GET \
  'https://developers.firstup.io/v2/feed/posts/{content_id}/engagement' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json

dataobject(Feeds.PostEngagement.Resource)

Response

application/json

{
  "data": {
    "id": 0,
    "user_id": 456,
    "liked_at": "2000-01-01T00:00:00Z",
    "bookmarked_at": "2000-01-01T00:00:00Z",
    "viewed_at": "2000-01-01T00:00:00Z",
    "shares": [ … ],
    "total_likes_count": 5,
    "total_shares_count": 0,
    "total_bookmarks_count": 0
  }
}

User Management

The User Management API adheres to the SCIM 2.0 protocol unless otherwise stated, and provides management and provisioning of users in a program.

Managing users requires that the acting user have a role of Program Manager or Administrator, and users can only create or update users with a role less than or equal to their own.

For further guidance on User Management, refer to:

User Management contextual overview.

User provisioning use case examples.

SCIM patching and user editing use case examples.

Custom user attributes overview.

User role and access.

Operations

User Groups

The Group Management API adheres to the SCIM 2.0 protocol unless otherwise stated, and provides management and provisioning of Groups and its members (Users) within a Program.

Managing Groups requires that the acting User have a role of Program Manager or Administrator, and Group read and/or write access.

Note: User groups are SCIM groups only. Currently this API does not support creating audiences.

Operations

Webhooks

The Webhooks API provides a mechanism for subscribing to events that occur within the Firstup platform to receive http payloads when those events occur. Use webhook subscriptions to trigger actions on your own application.

Webhook events are sent by the Firstup platform as POST requests to your webhook url. Each event contains a payload specific to that event. More information about the webhooks system, including a list of events that can be subscribed to, is available on the Webhooks page.

Operations

Assistant Inbox

Note: This API is getting deprecated and is replaced by the Notification Center.

Operations

User Roles

Operations

Notification Center

Operations

Firstup API (v2)

Content Publishing

Feeds

Return a user's feed of posts

Request

Responses

Was this helpful?

Return the details of a single post within a feed

Request

Responses

Was this helpful?

Return the engagement details of a single post within a feed

Request

Responses

Was this helpful?

User Management

User Groups

Webhooks

Assistant Inbox

User Roles

Notification Center