Skip to content

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>"
Download OpenAPI description
Languages
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

Fetch the details of a content post

Request

Read an existing content record. Returns a single record by identifier or by the content UUID.

Security
oauth2_as_a_user or oauth2_as_a_server
Path
content_idintegerrequired

ID of the detailed content post

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

Responses

Success

Bodyapplication/json
dataobject(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": { "id": 456, "version": 1, "uuid": "8b358e6b-11d4-4e89-bf7f-ec670e3398ed", "content_type": "article", "cover_image_alt": "Image of an elephant", "permalink_url": "https://onfirstup.com/acme/acmetimes/sc4#contents/456", "title": "Example Article Title", "summary": "Example article summary", "body": "Example article body", "state": "published", "accent_color": "#ae2225", "featured_label": "Save Pandora!", "featured": false, "author": {}, "channels": [], "source": {}, "template": {}, "visibility": "public", "shareable_url": "https://onfirstup.com/acme/acmetimes/sc4#contents/456", "language": "en", "is_translatable": true, "is_commentable": true, "comment_count": 5, "created_at": "2000-01-01T00:00:00Z", "updated_at": "2000-01-01T00:00:00Z", "published_at": "2000-01-01T00:00:00Z", "links": [], "images": [], "image_blocks": [], "videos": [], "initiatives": [] } }

Request

Update an existing content record. Content can be updated in any state, but some states have different validations. Any or all of the content attributes can be provided and only those provided will be updated.

This endpoint cannot be used to change content type, state, or topics. 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 updated record.

Security
oauth2_as_a_user or oauth2_as_a_server
Path
content_idintegerrequired

ID or UUID of the content post

Bodyapplication/json

Attributes of the content to update.

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"
sourceobject
templateobject
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

link_urlany

The url if the content_type is link

Example: "https://google.com"
curl -i -X PUT \
  'https://developers.firstup.io/v2/content/{content_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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",
    "source": {
      "post_id": "abc123",
      "posted_at": "2000-01-01T00:00:00Z"
    },
    "template": {
      "id": 234
    },
    "images": [
      {
        "image_url": "https://image.site.com/an_image.png"
      }
    ],
    "link_url": "https://google.com"
  }'

Responses

Content Updated

Bodyapplication/json
dataArray of objects(Content.Post.Resource)
Response
application/json
{ "data": [ {} ] }

Request

Archive an existing content post. Transition the content state from any state directly to "archived".

Response body contains the latest version of the content record.

Security
oauth2_as_a_user or oauth2_as_a_server
Path
content_idintegerrequired

ID or UUID of the content post

curl -i -X PUT \
  'https://developers.firstup.io/v2/content/{content_id}/archive' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Content Archived

Bodyapplication/json
dataobject(Content.Post.Resource)
Response
application/json
{ "data": { "id": 456, "version": 1, "uuid": "8b358e6b-11d4-4e89-bf7f-ec670e3398ed", "content_type": "article", "cover_image_alt": "Image of an elephant", "permalink_url": "https://onfirstup.com/acme/acmetimes/sc4#contents/456", "title": "Example Article Title", "summary": "Example article summary", "body": "Example article body", "state": "published", "accent_color": "#ae2225", "featured_label": "Save Pandora!", "featured": false, "author": {}, "channels": [], "source": {}, "template": {}, "visibility": "public", "shareable_url": "https://onfirstup.com/acme/acmetimes/sc4#contents/456", "language": "en", "is_translatable": true, "is_commentable": true, "comment_count": 5, "created_at": "2000-01-01T00:00:00Z", "updated_at": "2000-01-01T00:00:00Z", "published_at": "2000-01-01T00:00:00Z", "links": [], "images": [], "image_blocks": [], "videos": [], "initiatives": [] } }

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:

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
Operations
Operations