NAV Navbar
Logo
shell nodejs elixir

Introduction

Welcome to the Tagplay API! You can use our API to programmatically access the Tagplay product.

With Tagplay, you can post your content on social media to update your website automatically.

Update your content with Facebook Pages & Profiles, Instagram, Twitter and email. You can also use any social media management or content management tools of your choice. We redirect your content when it shares to social media.

You can use a certain #tag from one of your social media profiles to control which content goes where on your website.

This API documentation describes version 1 of the api service and can be found at https://api.tagplay.co/v1.

Data Objects

{
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 505,
    "previous_url": "/v1/project?offset=0",
    "next_url": "/v1/project?offset=40"
  },
  "meta": {
    "branded": false,
    "trigger_tags": []
  },
  "data": ObjectOrArray
}

All API calls reply with a root object. The resulting data from the query will be found under the data attribute of that object.

If the data is an array a pagination object will appear in the root describing pagination details.

Additionally, a meta object may contain some meta information for the data that may be useful for processing it (primarily, it is used by Tagplay’s own libraries). Currently, this object is empty except in the post endpoints, where it includes the properties branded, a boolean indicating whether Tagplay’s widget should include branding, and trigger_tags, a list of tags used in formulas sending to the feed whose posts are being fetched, which can be used to process the text of the post to remove those tags.

Media

{
  "id": "10f85f52-9e61-11e4-82fd-20c9d08a778d",
  "sources": [
    {
      "height": 640, "width": 640,
      "id": "1ec51076-9e61-11e4-8b5d-20c9d08a778d",
      "url": "http://example.com/1ec51076.jpg"
    },
    {
      "height": 320, "width": 230,
      "id": "1f36822e-9e61-11e4-a11b-20c9d08a778d",
      "url": "http://example.com/1f36822e.jpg"
    }
  ]
}
Parameter Type Description
id String Unique UUID for the Media
sources Array Array of Objects describing different sizes of the Media
sources[].id String UUID of the Media
sources[].height Integer Height of the Media
sources[].width Integer Width of the Media
sources[].url String URL to the Media

Provider

{
  "created_time": "2014-11-05T15:48:24.560047",
  "name": "instagram",
  "username": "example_user",
  "user_id": "4253645776",
  "origin": "http://example.com/49bc325e"
}
Parameter Type Description
name String Name of the Provider
created_time JSONDate Time the item was created at the Provider
origin String URL to the original social media post on the Provider (may be blank for some providers)
username String (Deprecated; use the username attribute on the user object instead.) Username of the user who posted to the Provider
user_id String (Deprecated; use the id attribute on the user object instead.) The ID of the user who posted to the Provider

User

{
  "id": "4253645776",
  "username": "example_user",
  "full_name": "Example User",
  "profile_picture": "http://example.com/2b45c78d.jpg"
}
Parameter Type Description
id String The ID of the user
username String The username of the user (may be blank for some providers)
full_name String The full name of the user (may be blank for some users)
profile_picture String The URL to the user’s profile picture 
{
  "href": "https://tagplay.co",
  "text": "https://tagplay.co",
  "description": null,
  "index": [14, 32]
}
Parameter Type Description
href String The URL to link to
text String Link text
description String A description of the link (optional)
index Array The start and end index of the link in the post text

Linked Metadata

{
  "href": "http://example.com/page",
  "title": "Page title",
  "description": "Page description",
  "image": MediaObject
}
Parameter Type Description
href String The URL to which the linked metadata points
title String The title of the linked page
description String The description of the linked page
image Media The image associated with the linked metadata

Location

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [
      101.22495889664,
      12.684491887585
    ]
  },
  "properties": {
    "name": "A place",
    "instagram_id": "534769453",
    "twitter_id": "4656835846858",
    "facebook_id": "1242464575684523413"
  }
}
Parameter Type Description
type String The type of location
geometry String The geometry of the location
geometry.type String The type of the geometry
geometry.coordinates Array A [longitude, latitude] array.
properties Object A set of optional extra information about the location
properties.name String The name of the location
properties.{provider}_id String The ID of the location given by the provider

Post

{
  "provider": ProviderObject,
  "user": UserObject,
  "added_time": "2014-11-05T15:48:23",
  "published_time": "2014-11-05T15:48:23",
  "removed_time": null,
  "id": "0020bad0-9e61-11e4-bf88-20c9d08a778d",
  "text": "@example_user https://tagplay.co Selfie at #tagplay",
  "normalized_text": "@example_user https://tagplay.co Selfie at tagplay",
  "stripped_text": "@example_user https://tagplay.co Selfie at",
  "tagless_text": "@example_user https://tagplay.co Selfie at",
  "type": "image",
  "image": MediaObject,
  "video": MediaObject,
  "tags": [ "tagplay" ],
  "mentions": [ "example_user" ],
  "links": [
    LinkObject,
    LinkObject
  ],
  "linked_metadata": LinkedMetadataObject,
  "location": LocationObject,
  "meta": {
    "pinned": false,
    "removed": false,
    "likes": 0,
    "flags": 0,
    "has_liked": false,
    "has_flagged": false
  }
}
Parameter Type Description
id String Unique UUID for the Post
type String Type of the Post
added_time JSONDate Time the Post was added to the feed
published_time JSONDate Time the Post was published in the feed
removed_time JSONDate Time the Post was removed from the feed, if it has been removed
provider Provider Provider info.
text String The original text
normalized_text String Normalized version of the text
stripped_text String Stripped version of the text
tagless_text String Tagless version of the text
image Media Linked image
video Media Linked video
tags Array Array of tag strings
mentions Array Array of usernames mentioned in the Post
links Array(Link) Array of link entities in the Post
linked_metadata Linked Metadata Information about associated link metadata
location Location GeoJSON info about the location where this Post was made
meta Object Object of meta information
meta.pinned Boolean Is the Post pinned to the top of the feed
meta.removed Boolean Has the Post been removed
meta.likes Integer Number of likes
meta.flags Integer Number of flags
meta.has_liked Boolean H
meta.has_flagged Boolean Have you flagged it?

Feed

{
  "id": "a10b01ac-c1e7-495b-acfb-93f1a10dac16",
  "name": "Me myself and Tagplay",
  "preview_media": {
    "id": "046f1ba0-6196-47f2-b40b-b21d81548246",
    "image": "http://example.com/1f36822e.jpg",
    "text": "Selfie at tagplay"
  },
  "public_media_count": 200
}
Parameter Type Description
id String Unique UUID for the Feed
name String The name of the Feed
public_media_count Integer Number of items in the Feed
preview_media Object Preview media object, the newest public Post in the Feed
preview_media.id String id of the Post the media is from
preview_media.image String URI of the media
preview_media.text String Text from the Post.

Project

{
  "id": "1cb0221e-c401-4721-977e-21748d4447bb",
  "name": "General project"
}
Parameter Type Description
id String Unique UUID for the Project
name String The name of the Project

Embed data

Our embed data comes from our Iframely server. Please check there for documentation of the Iframely API.

Authentication

var client = require('tagplay')({
  token: 'ABCDEFG:ABCDEFG:ABCDEFG'
});
client.getProject('project_id', function(error, body) {
  console.log(body); // json object
});

export TOKEN="ABCDEFG:ABCDEFG:ABCDEFG"
curl -X GET "https://api.tagplay.co/v1/project" \
  -H "Authorization: Bearer $TOKEN"

client = Tagplay.client("ABCDEFG:ABCDEFG:ABCDEFG")
Tagplay.Project.list!(client)

Tagplay uses JSON Web Tokens for authorization. You generate these from the Get Code/Designer section for each feed.

Projects

Get Project Info

var client = require('tagplay')({
  token: 'ABCDEFG:ABCDEFG:ABCDEFG'
});

client.getProject('project_id', function(error, body) {
  console.log(body); // json object
});

curl -X GET -H "Authorization: Bearer $TOKEN" \
"https://api.tagplay.co/v1/project/PROJECT_ID"

client = Tagplay.client("ABCDEFG:ABCDEFG:ABCDEFG")
Tagplay.Project.get!('project_id', client)

HTTP Request

GET /v1/project/:project_id

HTTP Result

Data will be a Project object.

Feed

List Feeds in Project

var client = require('tagplay')({
  token: 'ABCDEFG:ABCDEFG:ABCDEFG'
});

client.listFeed('project_id', function(error, body) {
  console.log(body); // json object
});

curl -X GET -H "Authorization: Bearer $TOKEN" \
"https://api.tagplay.co/v1/project/PROJECT_ID/feed"

client = Tagplay.client("ABCDEFG:ABCDEFG:ABCDEFG")
Tagplay.Feed.list!('project_id', client)

HTTP Request:

GET /v1/project/:project_id/feed

Query Parameters:

Parameter Default Description
limit 20 Limits the results to specified length.
offset 0 Starts results from the following item.

HTTP Result

Data will be an array of Feed items.

Get Feed Info

curl -X GET -H "Authorization: Bearer $TOKEN" \
"https://api.tagplay.co/v1/project/PROJECT_ID/feed/FEED_ID"


client = Tagplay.client("ABCDEFG:ABCDEFG:ABCDEFG")
Tagplay.Feed.get!('project_id', 'feed_id', client)

HTTP Request

GET /v1/project/:project_id/feed/:feed_id

HTTP Result

Data will be a Feed object.

Post

List Posts in Feed

var client = require('tagplay')({
  token: 'ABCDEFG:ABCDEFG:ABCDEFG'
});

client.listPost('project_id', 'feed_id', function(error, body) {
  console.log(body); // json object
});

curl -X GET -H "Authorization: Bearer $TOKEN" \
"https://api.tagplay.co/v1/project/PROJECT_ID/feed/FEED_ID/post"

client = Tagplay.client("ABCDEFG:ABCDEFG:ABCDEFG")
Tagplay.Post.list!('project_id', 'feed_id', client)

HTTP Request

GET /v1/project/:project_id/feed/:feed_id/post

Query Parameters

Parameter Default Description
limit 20 Limits the results to specified length.
offset 0 Starts results from the following item.

HTTP Result

Data will be a list of Post objects.

Get Post

var client = require('tagplay')({
  token: 'ABCDEFG:ABCDEFG:ABCDEFG'
});

client.getPost('project_id', 'feed_id', 'post_id', function(error, body) {
  console.log(body); // json object
});

curl -X GET -H "Authorization: Bearer $TOKEN" \
"https://api.tagplay.co/v1/project/PROJECT_ID/feed/FEED_ID/post/POST_ID"

client = Tagplay.client("ABCDEFG:ABCDEFG:ABCDEFG")
Tagplay.Post.get!('project_id', 'feed_id', 'post_id' client)

HTTP Request

GET /v1/project/:project_id/feed/:feed_id/post/:post_id

HTTP Result

Data will be a Post object.

Flag Post

var client = require('tagplay')({
  token: 'ABCDEFG:ABCDEFG:ABCDEFG'
});

client.flagPost('project_id', 'feed_id', 'post_id', function(error, body) {
  console.log(body); // json object
});

curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.tagplay.co/v1/project/PROJECT_ID/feed/FEED_ID/post/POST_ID/flag"

client = Tagplay.client("ABCDEFG:ABCDEFG:ABCDEFG")
Tagplay.Post.flag!('project_id', 'feed_id', 'post_id' client)

HTTP Request

POST /v1/project/:project_id/feed/:feed_id/post/:post_id/flag

HTTP Result

Empty Response

Unflag Post

var client = require('tagplay')({
  token: 'ABCDEFG:ABCDEFG:ABCDEFG'
});

client.unflagPost('project_id', 'feed_id', 'post_id', function(error, body) {
  console.log(body); // json object
});

curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.tagplay.co/v1/project/PROJECT_ID/feed/FEED_ID/post/POST_ID/unflag"


client = Tagplay.client("ABCDEFG:ABCDEFG:ABCDEFG")
Tagplay.Post.unflag!('project_id', 'feed_id', 'post_id' client)

HTTP Request

POST /v1/project/:project_id/feed/:feed_id/post/:post_id/unflag

HTTP Result

Empty Response

Like Post

var client = require('tagplay')({
  token: 'ABCDEFG:ABCDEFG:ABCDEFG
'});

client.likePost('project_id', 'feed_id', 'post_id', function(error, body) {
  console.log(body); // json object
});

curl -X POST -H "Authorization: Bearer $TOKEN" |
"https://api.tagplay.co/v1/project/PROJECT_ID/feed/FEED_ID/post/POST_ID/like"

client = Tagplay.client("ABCDEFG:ABCDEFG:ABCDEFG")
Tagplay.Post.like!('project_id', 'feed_id', 'post_id' client)

HTTP Request

POST /v1/project/:project_id/feed/:feed_id/post/:post_id/like

HTTP Result

Empty Response

Unlike Post

var client = require('tagplay')({
  token: 'ABCDEFG:ABCDEFG:ABCDEFG'
});

client.unlikePost('project_id', 'feed_id', 'post_id', function(error, body) {
  console.log(body); // json object
});

curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.tagplay.co/v1/project/PROJECT_ID/feed/FEED_ID/post/POST_ID/unlike"

client = Tagplay.client("ABCDEFG:ABCDEFG:ABCDEFG")
Tagplay.Post.unlike!('project_id', 'feed_id', 'post_id' client)

HTTP Request

POST /v1/project/:project_id/feed/:feed_id/post/:post_id/unlike

HTTP Result

Empty Response

Embeds

var client = require('tagplay')({
  token: 'ABCDEFG:ABCDEFG:ABCDEFG'
});

client.getEmbedInfo('http://example.com', options, function(error, body) {
  console.log(body); // json object
});

curl -X GET -H "Authorization: Bearer $TOKEN" \
"https://api.tagplay.co/v1/embed?url=link"

HTTP Request

GET /v1/embed

Query Parameters

Parameter Default Description
url - The URL to retrieve embed information for.
(other) - For more query parameters, see the Iframely documentation.

HTTP Result

Data will be an Embed Data object provided by our Iframely server.

Libraries

Official Libraries

Langage Source Package Docs
Javascript/NodeJS GitHub NPM
Elixir GitHub Hex HexDocs
shell nodejs elixir