Fetch a collection of content

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

List all followers of a topic

Request

Returns a list of all users who follow the topic, and allows for pagination of the records.
Response body is an array of records.

Security

oauth2_as_a_user or oauth2_as_a_server

Path

channel_idintegerrequired

ID of the topic. The topic must exist in the program.

Query

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

curl -i -X GET \
  'https://developers.firstup.io/v2/channels/{channel_id}/followers?page.size=0&page.number=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json

dataArray of objects(Content.ChannelFollower.Resource)required

data[].avatar_urlstring

Path to an image representing the follower.

Example: "https://example.com/avatar.png"

data[].display_namestring

The name to display as the follower.

Example: "Some User"

data[].user_idinteger

The Firstup user_id of the follower.

Example: 123

data[].full_namestring

Full name of the follower.

Example: "Bobby Brown"

data[].usernamestring

Username of the follower.

Example: "BobbyBrown"

data[].employee_idstring

Employee ID of the follower.

Example: "employee1"

metaobject

Response

application/json

{
  "data": [
    { … }
  ],
  "meta": {
    "pagination": { … }
  }
}

Fetch a collection of content

Request

Returns a list of content records and allows for sorting, filtering, and pagination of the records.
Response body is an array of records.

Security

oauth2_as_a_user or oauth2_as_a_server

Query

filter.content_typeArray of strings

Limit returned records to those that match the content_type(s) provided.

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

filter.stateArray of strings

Limit returned records to those that match the state(s) provided.

Items Enum"draft""published""review""archived""scheduled""processing""processing_error""any"

filter.targeted_channelsstring

Return content posts that are assigned to targeted topics

Default "any"

Enumtruefalse"any"

filter.channels.idArray of integers

Return content posts that are assigned to the topic.

filter.initiative_tags.idArray of integers

Return content posts that are tagged with the provided initiative tags. Defaults to all content.

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"

filter.source.typestring

Limit returned records to records using the provided source.type value.

Default "any"

Enum"submitted""pinterest""rss""facebook""twitter""instagram""socialchorus_cpcm""studio""oauth_client""any"

filter.source.post_idstring

Limit results to records with the given unique identifier on the source system.

filter.created_at.fromstring(date-time)

Limit results to records created at or after this time, equivalent to a range filter of "{value} <= created_at <= now". Use in combination with created_at.to to specify a limited upper bound on the value range. Must be formatted as an ISO8601 timestamp or datestamp. Datestamps are assumed to be in UTC.

filter.created_at.tostring(date-time)

Limit results to records created at or before this time, equivalent to a range filter of "forever <= created_at <= {value}". Use in combination with created_at.from to specify a limited lower bound on the value range. Must be formatted as an ISO8601 timestamp or datestamp. Datestamps are assumed to be in UTC.

filter.updated_at.fromstring(date-time)

Limit results to records created at or after this time, equivalent to a range filter of "{value} <= updated_at <= now". Use in combination with updated_at.to to specify a limited upper bound on the value range. Must be formatted as an ISO8601 timestamp or datestamp. Datestamps are assumed to be in UTC.

filter.updated_at.tostring(date-time)

Limit results to records created at or before this time, equivalent to a range filter of "forever <= updated_at <= {value}". Use in combination with updated_at.from to specify a limited lower bound on the value range. Must be formatted as an ISO8601 timestamp or datestamp. Datestamps are assumed to be in UTC.

filter.published_at.fromstring(date-time)

Limit results to records created at or after this time, equivalent to a range filter of "{value} <= published_at <= now". Use in combination with published_at.to to specify a limited upper bound on the value range. Must be formatted as an ISO8601 timestamp or datestamp. Datestamps are assumed to be in UTC.

filter.published_at.tostring(date-time)

Limit results to records created at or before this time, equivalent to a range filter of "forever <= published_at <= {value}". Use in combination with published_at.from to specify a limited lower bound on the value range. Must be formatted as an ISO8601 timestamp or datestamp. Datestamps are assumed to be in UTC.

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

curl -i -X GET \
  'https://developers.firstup.io/v2/content?filter.content_type=article&filter.state=draft&filter.targeted_channels=true&filter.channels.id=0&filter.initiative_tags.id=0&filter.visibility=public&filter.featured=true&filter.source.type=submitted&filter.source.post_id=string&filter.created_at.from=2019-08-24T14%3A15%3A22Z&filter.created_at.to=2019-08-24T14%3A15%3A22Z&filter.updated_at.from=2019-08-24T14%3A15%3A22Z&filter.updated_at.to=2019-08-24T14%3A15%3A22Z&filter.published_at.from=2019-08-24T14%3A15%3A22Z&filter.published_at.to=2019-08-24T14%3A15%3A22Z&page.size=0&page.number=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json

dataArray of objects(Content.Post.Resource)required

data[].idinteger

Unique identifier for this post.

Example: 456

data[].versioninteger

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

1 - Legacy Studio
2 - Creator Studio

Enum12

data[].uuidstring(uuid)

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

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[].cover_image_altstring

The url of the post on the Firstup platform. This property will only be returned for V2 content which can be viewed but not created via the Firstup API.

Example: "Image of an elephant"

data[].permalink_urlstring

The url of the post on the Firstup platform.

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

data[].titlestring

The post title. Can also be considered the headline.

Example: "Example Article Title"

data[].summarystring

Short summary of the post.

Example: "Example article summary"

data[].bodystring

The body of the post.

Example: "Example article body"

data[].statestring

The state of the post. One of: archived, draft, processing, processing_error, published, review or scheduled.

Example: "published"

data[].accent_colorstring

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

Example: "#ae2225"

data[].featured_labelstring

The content's feature label

Example: "Save Pandora!"

data[].featuredboolean

Whether the post is featured.

Example: false

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

data[].channelsArray of objects

A list of the topics this post is published to.

data[].sourceobject

data[].templateobject

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[].shareable_urlstring

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

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

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[].created_atstring(date-time)

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

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

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[].linksArray of objects

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

data[].image_blocksArray of objects(Content.ImageBlock.Resource)

All image blocks of Creator Studio content

data[].videosArray of objects(Content.Video.Resource)

data[].initiativesArray of objects

A list of the initiatives.

metaobject

Response

application/json

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

Create a new content post

Request

Create a new content item and select what topics will include the content. The new content will be created in the “draft” state.

This endpoint only creates the post. If applicable, an image may be added later via the appropriate endpoint. If author.user_id is provided, it will be used to determine display_name and avatar_url, overriding any values provided for display_name and avatar_url.

Response body data will be the newly created record.

Security

oauth2_as_a_user or oauth2_as_a_server

Bodyapplication/json

Attributes of the content to create.

content_typestring

The type of content to create

Default "article"

Enum"article""link""video""image"

Example: "article"

titleany

A title for the post

Example: "Example Post Title"

bodyany

The body text for the post. HTML is permitted.

Example: "Example post body"

summaryany

Post summary blurb

Example: "Example post summary"

authorobject(Content.Post.Resource.author)

featuredboolean

Whether the post is featured.

Example: true

featured_labelstring

The featured label.

Example: "A Label"

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.

Default "private"

Enum"private""public"

Example: "private"

channelsArray of objects

A list of topics the content will be published to.

sourceobject

imagesArray of objects(Content.Creation.Images)

An ordered list of images for this content.

Images are only validated for content of "image" type. There is a limit of ten images.

Note: The content returned immediately after content creation or modification contains will not contain the final image URIs due to additional post-processing

templateobject

link_urlany

The url if the content_type is link

curl -i -X POST \
  https://developers.firstup.io/v2/content \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "content_type": "article",
    "title": "Example Post Title",
    "body": "Example post body",
    "summary": "Example post summary",
    "author": {
      "avatar_url": "https://example.com/avatar.png",
      "display_name": "Some User",
      "user_id": 123
    },
    "featured": true,
    "featured_label": "A Label",
    "visibility": "private",
    "channels": [
      {
        "id": 789,
        "hidden": false
      }
    ],
    "source": {
      "post_id": "string",
      "posted_at": "string"
    },
    "images": [
      {
        "image_url": "https://image.site.com/an_image.png"
      }
    ],
    "template": {
      "id": 0
    },
    "link_url": null
  }'

Responses

Content Created

Bodyapplication/json

dataArray of objects(Content.Post.Resource)required

data[].idinteger

Unique identifier for this post.

Example: 456

data[].versioninteger

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

1 - Legacy Studio
2 - Creator Studio

Enum12

data[].uuidstring(uuid)

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

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[].cover_image_altstring

The url of the post on the Firstup platform. This property will only be returned for V2 content which can be viewed but not created via the Firstup API.

Example: "Image of an elephant"

data[].permalink_urlstring

The url of the post on the Firstup platform.

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

data[].titlestring

The post title. Can also be considered the headline.

Example: "Example Article Title"

data[].summarystring

Short summary of the post.

Example: "Example article summary"

data[].bodystring

The body of the post.

Example: "Example article body"

data[].statestring

The state of the post. One of: archived, draft, processing, processing_error, published, review or scheduled.

Example: "published"

data[].accent_colorstring

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

Example: "#ae2225"

data[].featured_labelstring

The content's feature label

Example: "Save Pandora!"

data[].featuredboolean

Whether the post is featured.

Example: false

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

data[].channelsArray of objects

A list of the topics this post is published to.

data[].sourceobject

data[].templateobject

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[].shareable_urlstring

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

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

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[].created_atstring(date-time)

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

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

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[].linksArray of objects

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

data[].image_blocksArray of objects(Content.ImageBlock.Resource)

All image blocks of Creator Studio content

data[].videosArray of objects(Content.Video.Resource)

data[].initiativesArray of objects

A list of the initiatives.

Response

application/json

{
  "data": [
    { … }
  ]
}

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

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

List all followers of a topic

Request

Responses

Was this helpful?

Fetch a collection of content

Request

Responses

Was this helpful?

Create a new content post

Request

Responses

Was this helpful?

Feeds

User Management

User Groups

Webhooks

Assistant Inbox

User Roles

Notification Center

Firstup API (v2)

Content Publishing

List all followers of a topic

Request

Responses

Was this helpful?

Fetch a collection of content

Request

Responses

Was this helpful?

Create a new content post

RequestExpand all

Responses

Was this helpful?

Feeds

User Management

User Groups

Webhooks

Assistant Inbox

User Roles

Notification Center

Request