What's this

Introduction

Read this section to learn about the Content endpoints and their features

One of the most important elements of the 10Centuries platform is its ability to quickly handle content. In this section we'll look at the available endpoints that are available to interact with the content belonging to a given account. All text is stored in Markdown format, and posts that have embedded HTML are parsed as much as possible to bring the content in line with the Standard Markdown formatting specifications. This is part of 10Centuries' promise to keep data readable for future generations.

Sections

  1. Creating a Post
  2. Deleting a Post
  3. Editing a Post
  4. Listing Posts
  5. Retrieving Specific Posts
  6. Collecting Posts
  7. Searching Posts

Common Interactions

  1. Pinning a Post
  2. Reposting a Post
  3. Starring a Post

Creating a Post

10Centuries makes publishing various post types a snap. Anything that is published must go through this single endpoint. There are a number of options, and different post.type values that can be returned based on the information passed to the API. Any API request that can create or modify data must have a valid authorization token in the HTTP header.

From your application, send a request to the following endpoint:

POST https://api.10centuries.org/content

Required Data:

content: {post content}

The post content can be between 1 and 8192 bytes in length when only the content field is used. Posting content without a title will create a social object, sometimes called a Blurb.

Optional Data:

title: {Title for Blog Post, Draft, Page, or Podcast} channel_id: {Channel ID to Publish Content To} post_id: {Post ID of Blog Post, Draft, Page, or Podcast Being Updated} reply_to: {Post ID of Object Being Replied To} slug: {URL slug for a Blog Post, Draft, Page, or Podcast} type: {The Post Object Type [Can Be Overridden by API]} send_blurb: {Write a Blurb to Notify Followers of New Blog Post/Podcast (Y/N Value Only)} pubdts: {Publication Date in YYYY-MM-DD HH:MM:SS Format [Defaults to Now]} expydts: {Expiration Date in YYYY-MM-DD HH:MM:SS Format [Defaults to Never]} expyhrs: {Number of Hours to Expire Post Object In [Overrides expydts]} privacy_type: {Privacy Type of Post} passwd: {Access Password for published Blog Post, Page, or Podcast} simple_posts: {Return a "Simple" Data Set [Y/N]}

This information can be send URL-encoded in the POST body or as a JSON package.

Example:

curl -X POST -H "Authorization: {Authorization Token}" \ -H "Content-Type: application/x-www-form-urlencoded" -d "content=This is, perhaps, one of the most boring posts in the history of the universe." \ "https://api.10centuries.org/content"

If the post was successful, the API will respond with a JSON package:

{ "meta": { "code": 200 }, "data": [ { "id": 3511, "parent_id": false, "title": "", "slug": "3511", "type": "post.micro", "privacy": "visibility.public", "guid": "1c887cc2388bb13100ed5734e16d95dd8df5bf7a", "content": { "text": "This is, perhaps, one of the most boring posts in the history of the universe.", "html": "<p>This is, perhaps, one of the most boring posts in the history of the universe.</p>", "summary": false, "banner": false }, "audio": false, "tags": false, "urls": { "canonical_url": "/posts/3511", "full_url": "10centuries.org/posts/3511", "alt_url": "10centuries.org/3511", "is_https": true }, "thread": false, "mentions": false, "account": [{account object}], "channel": {channel object}, "client": {client object}, "created_at": "2016-02-20T10:42:34Z", "created_unix": 1455964954, "publish_at": "2016-02-20T10:42:34Z", "publish_unix": 1455964954, "updated_at": "2016-02-20T10:42:34Z", "updated_unix": 1455964954, "expires_at": false, "expires_unix": false, "is_mention": false, "you_starred": false, "you_pinned": false, "you_reblurbed": false, "stars": false, "blurbs": false, "parent_post": false, "follows_you": true, "you_follow": true, "you_muted": false, "you_blocked": false, "is_visible": true, "is_deleted": false } ] }

If the object is a Blurb and is determined to be a duplicate of an immediately previous Blurb of the same size, the API will respond with an error:

{ "meta": { "code": 404, "text": "Duplicate Post!" }, "data": false }

If the simple_posts option is set to Y then a number of the tail-end values will not be included.

If posting failed or there was some other problem, the API will respond with an error:

{ "meta": { "code": 404, "text": "No Text to Post" }, "data": false }

If the meta.text key is present in this result, you must show a modal dialog or equivalent containing this message.

Deleting a Post

Deleting a Post just just as easy as creating one. From your application, send a request to the following endpoint:

DELETE https://api.10centuries.org/content/{Post ID}

Alternatively, a post_id variable can be passed through either a URL-encoded web form object, or in a JSON object. A post_id value will override any Post ID in the URL. Of course, only the creator of a post can delete it.

Example:

curl -X DELETE -H "Authorization: {Authorization Token}" \ -H "Content-Type: application/x-www-form-urlencoded" \ "https://api.10centuries.org/content/{Post ID}"

If the action was successful, the API will respond with a JSON package:

{ "meta": { "code": 200 }, "data": { "id": {Post ID}, "is_visible": false, "is_deleted": true } }

If the action failed or there was some other problem, the API will respond with an error:

{ "meta": { "code": 404, "text": "Invalid Post ID" }, "data": false }

If the meta.text key is present in this result, you must show a modal dialog or equivalent containing this message.

Editing a Post

{Coming Soon to a Document Near You ...}

Listing an Account's Posts

{Coming Soon to a Document Near You ...}

Retrieving Specific Posts

Retrieving posts can be done by passing a comma-separated list of IDs to the API or, if requesting a single post, appending it to the appropriate endpoint. To collect posts, send a request to the following endpoint:

GET https://api.10centuries.org/content

Example:

curl -X GET -H "Authorization: {Authorization Token}" \ -H "Content-Type: application/x-www-form-urlencoded" -d "post_ids=1,2,3" \ "https://api.10centuries.org/content"

If the post was successful, the API will respond with a JSON package containing 3 post objects. Deleted objects or with non-public visibility settings may be excluded from the results if an authorization token is not sent with the request.

Retrieving a single post can be done with the information below:

GET https://api.10centuries.org/content/{Post ID}

Example:

curl -X GET -H "Authorization: {Authorization Token}" \ -H "Content-Type: application/x-www-form-urlencoded" \ "https://api.10centuries.org/content/{Post ID}"

If the Post exists and is visible, the API will respond with a JSON package:

{ "meta": { "code": 200 }, "data": [ { "id": 1, "parent_id": false, "title": "", "slug": "1", "type": "post.micro", "privacy": "visibility.public", "guid": "c4febde74f8f84917845c0cce9dd2253bace5293", "content": { "text": "Hello world. Welcome to 2016.", "html": "<p>Hello world. Welcome to 2016.</p>", "summary": false, "banner": false }, "audio": false, "tags": [{Tags Object}], "urls": { "canonical_url": "/posts/1", "full_url": "10centuries.org/posts/1", "alt_url": "10centuries.org/1", "is_https": true }, "thread": false, "mentions": false, "account": [{Account Object}], "channel": {Channel Object}, "client": {Client Object}, "created_at": "2016-01-01T09:00:00Z", "created_unix": 1451638800, "publish_at": "2016-01-01T09:00:00Z", "publish_unix": 1451638800, "updated_at": "2016-01-01T09:00:00Z", "updated_unix": 1451638800, "expires_at": false, "expires_unix": false, "is_mention": false, "you_starred": false, "you_pinned": false, "you_reblurbed": false, "stars": false, "blurbs": false, "parent_post": false, "follows_you": true, "you_follow": true, "you_muted": false, "you_blocked": false, "is_visible": true, "is_deleted": false } ] }

If the Post does not exist and does not have any permissions preventing the display of the object, the API will respond with the following JSON package:

{ "meta": { "code": 404, "text": "Post Does Not Exist" }, "data": false }

Collecting Blurbs

Retrieving blurbs is very similar to retrieving specific posts, but do not require knowledge of which Post numbers belong to a Blurb. There are a number of endpoints specifically for the retrieval of Blurbs.

Retrieve the Global Timeline (No Authentication Required)

GET https://api.10centuries.org/content/blurbs/global

Retrieve an Account's Home Timeline

GET https://api.10centuries.org/content/blurbs/home

Retrieve an Account's Interactions

GET https://api.10centuries.org/content/blurbs/interactions

Retrieve an Account's Mentions

GET https://api.10centuries.org/content/blurbs/mentions

Retrieve an Account's Pins

GET https://api.10centuries.org/content/blurbs/pins

Optional Data:

count: {The number of posts to retrieve [1~200]} before_id: {Retrieve Only Posts Before a Specified ID} before_unix: {Retrieve Only Posts Published Before a Specified Unix Timestamp} since_id: {Retrieve Only Posts After a Specified ID} since_unix: {Retrieve Only Posts Published After a Specified Unix Timestamp} simple_posts: {Return a "Simple" Data Set [Y/N]}

Example:

curl -X GET -H "Authorization: {Authorization Token}" \ -H "Content-Type: application/x-www-form-urlencoded" -d "since_unix=1234567890" \ "https://api.10centuries.org/content/blurbs/global"

The above request will return the 50 most recent Blurbs posted to the Global timeline. If the request does not include an authorization token, then only Posts that are Visible and Public will be displayed. Keep in mind that Blurbs may not be in numeric order. Posts can be future-dated, back-dated, and otherwise scheduled for release whenever the creator would like. Using since_unix is the recommended way to collect new Blurbs when reading a timeline.

If the simple_posts option is set to Y then a number of the tail-end values will not be included.

Retrieving Blurbs from a Specific Account

You can also collect Blurbs from a specific account with the following endpoint:

GET https://api.10centuries.org/users/blurbs/{account_id}

Pinning a Post

Sometimes we need to mark a post for later but don't want to Star it as the action may be misunderstood. For these reasons, Pins were created. At the moment, Pins come in six colours:

  • (#000000) Black
  • (#0000ff) Blue
  • (#00ff00) Green
  • (#ffa500) Orange
  • (#ff0000) Red
  • (#ffff00) Yellow

To set a Pin, send a request to the following endpoint:

POST https://api.10centuries.org/content/pin

Required Data:

post_id: {a valid Post ID} colour: {a hex color}

Alternatively, color (without the 'u') can be passed to the API.

Note: At the moment pins are limited to the six listed above, but future updates will allow people to set their own colours in addition to the six default ones. Invalid hex codes passed will be ignored.

Reposting a Post

Any object in 10Centuries can be Reposted, but this does not mean that a repost will be visible in a given timeline or channel. For the moment, only Objects published to channel_id=1 will be visible. Future updates may change this.

To Repost an object, send a request to the following endpoint:

POST https://api.10centuries.org/content/repost/{Post ID}

Reposting an object will return the new Post object with the Parent object embedded. To delete a Repost, use the Delete Post endpoint.

Note: Objects can be Reposted multiple times. There is no duplicate post functionality in place for this feature at this time.

Starring a Post

Any object in 10Centuries can technically be Starred, but they are currently limited to Post objects.

To Star an object, send a request to the following endpoint:

POST https://api.10centuries.org/content/star/{Post ID}

If the Post exists and the Star action completed successfully, the API will respond with a Post JSON package:

{ "meta": { "code": 200 }, "data": [ { ⋮ "stars": [ { "id": 1, "name": "@matigo", "avatar_url": "//cdn.10centuries.org/NtyZNP/325a0899a1f05a31d6bc1d54bccb0967.jpg", "starred_at": "2016-02-20 13:40:39", "starred_unix": 1455975639 } ], ⋮ } ] }

To Unstar a post, send the same request again. The function currently acts as a reversible Boolean.

Search will return a list of posts sorted according to most recent rather than the search score of the post. Simply query the endpoint with a word or series of words you are looking for.

From your application, send a request to the following endpoint:

GET https://api.10centuries.org/content/blurbs/search

Required Data:

filter: {an account name, a word or series of words}

The words must be 4 characters in length or longer.

Optional Data:

count: {The number of posts to retrieve [1~200]} before_id: {Retrieve Only Posts Before a Specified ID} before_unix: {Retrieve Only Posts Published Before a Specified Unix Timestamp} since_id: {Retrieve Only Posts After a Specified ID} since_unix: {Retrieve Only Posts Published After a Specified Unix Timestamp} simple_posts: {Return a "Simple" Data Set [Y/N]}