NAV Navbar
shell

General

Access tokens

We’re following the Oauth2 conventions for regulating access to our API.

Unless mentioned otherwise, we require an access token to access our API. The access token will define which information and actions your applications can access.

We use two types of access tokens:

  1. Application only access token
    The application only access tokens will give you access to publicly available information and actions. Use this type of access token if you want to retrieve content from our side independent from any users.
    This is equivalent to accessing the site as a logged out user.
  2. User access token
    User access tokens extend your access rights to allow your application to access content and actions which have restricted visibility and are available for the user the access token was issued for. The user access token allows you to retrieve content and execute actions on behalf of the user the token was issued for.
    This is equivalent to accessing the site as a logged in user.

Request authorization

Example of authorized request

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer 4aec18d02527e83d56b87c8699b65649f' \
  -X POST https://api.creatubbles.com/v2/creations

To authorize a request, the access_token has be sent in the Authorization header. See authentication section for details.

Locales

You can specify the locale for API calls. If you do, error messages and other locale specific content will be returned in the specified locale.

To set a locale you need to specify it in the Accept-Language header. Use values like: “en”, “ja”, “it”, etc.

When you send a request using a user access token, we will use the user’s selected locale by default unless you specify locale in the header of your request.

Additional data returned in Meta

  {
    "links": {...},
    "meta": {
      "total_pages": 3,
      "total_count": 15,
      "user_bubbled_creations": ["bNzO1Rmv"],
      "user_bubbled_users": ["xNzO3Rmv"],
      "user_bubbled_galleries": ["aNzO2Rmv"],
      "abilities":[{
          "id":"creation:YNzO8Rmv:edit",
          "type":"abilities",
          "relationships":{},
          "attributes": {
            "resource_type":"creation",
            "resource_id":"YNzO8Rmv",
            "permission":true,
            "operation":"edit"
          }
        },
        {
          "id":"creation:YNzO8Rmv:report",
          "type":"abilities",
          "relationships":{},
          "attributes":{
            "resource_type":"creation",
            "resource_id":"YNzO8Rmv",
            "permission":false,
            "operation":"report"
          }
        }
      ]
    },
    "data":[...]
  }

In returned JSON’s meta hash we sometimes return additional information:

  1. Creations / Users / Galleries index actions return user_bubbled_creations or user_bubbled_users or user_bubbled_galleries array, which contains ids of the resources in data which are bubbled by current user.

  2. Creations / Users index actions return abilities array, containing sets of current users’s access rights regarding each resource returned

  3. All index actions return also:

    • total_pages - number of content pages available
    • total_count - number of content items available
  4. Users retun followed_users array, which contains ids of users in data that are followed by current user.

Included objects

There is often a situation when except the object(s) loaded by the request you also need related objects to be returned. Instead of generating additional request, you can use the included route from the response to get those data.

{
  "data": { ... },
  "included": [
    {
      "id": "oCglzp9F",
      "type": "users",
      "attributes": { ... },
      "relationships": {
        "school": {
          "data": null
        },
        "custom_style": {
          "data": {
            "id": "123",
            "type": "custom_styles"
          }
        }
      }
    }
  ]
}

To get information about included objects for each request, see the sections (list and single) dedicated for requested resource.

This included root contains the array of objects in JsonAPI format.

Authorization

What follows are descriptions, sample usage, outputs, and server outputs for each of the Creatubbles API endpoints. To authorize requests you need an access_token.

See: General section for example of authorized request. We deliver few different flows to achieve it.

Client credentials flow

The client credentials flow will return an access token only associated with your application, not with a user. This allows access public resources, allowed for logged out users. You won’t have access to any private user data.

To retrieve this client only access token, only one step is required:

  1. POST /v2/oauth/token - with your client credentials (see Client credentials: Create Token).

The API will then return an access token in the response. After an access token was issued, you can send authorized requests by passing it to the API via the Authorization request header (see Access Token).

Client credentials: Create Token

Request - authorized using arguments

curl \
  -H 'Accept: application/json' \
  -F grant_type=client_credentials \
  -F client_id=YOUR_APP_ID \
  -F client_secret=YOUR_APP_SECRET \
  -X POST https://api.creatubbles.com/v2/oauth/token

Request - authorized via header

curl \
  -F grant_type=client_credentials \
  -H 'Accept: application/json' \
  -H Authorization: Basic czZCaGRSa2F0MzpnWDFmQmF0M2JW \
  -X POST https://api.creatubbles.com/v2/oauth/token

Response

{
  "access_token": "eecc03848ed5431631f257c7c8",
  "token_type": "bearer"
}

This describes the client_credentials OAuth grant type for retrieving an access token. Access tokens retrieved via this grant type are not associated with a user and allow access to public resources, allowed for logged out users.

Request

POST /v2/oauth/token

Params

Name description
grant_type set to client_credentials
client_id your application id
client_secret your application secret code

Access Restrictions

Possible Responses

Errors:

Success:

Authorization code flow

The authorization code flow allows you to get an authenticated user access token without asking the user for their credentials.

The general flow is the following:

  1. redirect the user’s browser to /v2/oauth/authorize with response_type=code, your client ID and a redirect_uri as parameters to start authentication flow (see Authorization code: Authorize).
  2. after the user successfully authorized access for your app, they will be redirected back to your app to given redirect_uri, including a code parameter.
  3. POST /v2/oauth/token - with received code to get the access token (see Authorization code: Create Token).

In the first step, the API will create and return an authorization code. You’ll redirect the user’s browser to the specified URL to complete the authentication with given code as argument. This endpoint corresponds to the OAuth 2 authorization endpoint, section 3.1

Authorization code: Authorize

Redirect user to authorize

open https://api.creatubbles.com/v2/oauth/authorize\?\
response_type=code\&\
redirect_uri=https://yourawesomeapp.com/oauth/callback/creatubbles\&\
client_id=YOUR_APP_ID

Handle redirect

# after authorization, browser will redirect to
# https://yourawesomeapp.com/oauth/callback/creatubbles
# with code parameter

Use this URL to start the authorization code flow.

Request

Redirect user to

/v2/oauth/authorize?response_type=code&client_id=:client_id&redirect_uri=:redirect_uri

Params

Name description
response_type ‘code’ to initiate this code flow
username this is an email of logged in username (optional)
client_id your application id
redirect_uri landing page on your app after authentication is completed

Access Restrictions

Authorization code: Create Token

Request for accessing the token

curl \
  -H 'Accept: application/json' \
  -F grant_type=authorization_code \
  -F client_id=YOUR_APP_ID \
  -F client_secret=YOUR_APP_SECRET \
  -F redirect_uri=https://yourawesomeapp.com/oauth/callback/creatubbles \
  -F code=fd0847dbb559752d932dd3c1ac34ff98d27 \
  -X POST https://api.creatubbles.com/v2/oauth/token

Response

{
  "access_token":"dbaf9757982a9e738f05d249b7b5b4a2",
  "token_type":"bearer"
}

This describes the authorization_code OAuth grant type for exchanging code retrieved via Authorization code: Authorize into an access token. Access tokens retrieved via this grant type are associated with a user and allow full access to the user’s resources.

Request

POST /v2/oauth/token

Params

Name description
grant_type set to authorization_code
client_id your application id
client_secret your application secret code
redirect_uri Required when code flow is chosen. Redirect URI need to match the url that the flow has been initiated by
code code passed to your application by completing step 1 of the authorization code flow

Access Restrictions

Possible Responses

Errors:

Success:

User switch flow

The user switch flow allows you to get an authenticated user access token for a managed creator. This is a custom OAuth flow.

The general flow is the following:

  1. get an access token for the main user.
  2. POST /v2/oauth/token - with the managed creator (see User switch: Create Token).

User switch: Create Token

Request for accessing the token

curl \
  -H 'Accept: application/json' \
  -F grant_type=user_switch \
  -F access_token=fd0847dbb559752d932dd3c1ac34ff98d27 \
  -F target_user_id=D8qqTgdq \
  -X POST https://api.creatubbles.com/v2/oauth/token

Response

{
  "access_token":"dbaf9757982a9e738f05d249b7b5b4a2",
  "token_type":"bearer"
}

This describes the user_switch OAuth grant type, a custom grant type. It allows you to retrieve an access token for one of the current user’s managed creators without their password. Access tokens retrieved via this grant type are associated with a user and allow full access to the user’s resources.

Request

POST /v2/oauth/token

Params

Name description
grant_type set to user_switch
access_token current user’s access token
target_user_id the user for which to obtain an access token
group_id (optional) limits further user switching to the given group, see Groups API

Access Restrictions

Possible Responses

Errors:

Success:

Abilities

Get specific ability

From meta section in requests to other endpoints:

{
  "data": { },
  "meta": {
    "abilities": [
      {
        "type": "abilities",
        "id": "creation:D8qqTgdq:edit",
        "attributes": {
          "resource_type": "creation",
          "resource_id": "D8qqTgdq",
          "operation": "edit",
          "permission": false
        }
      }
    ]
  }
}

Requesting specific abilities:

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X GET https://api.creatubbles.com/v2/abilities/creation:D8qqTgdq:edit

Response:

{
  "data": {
    "type": "abilities",
    "id": "creation:D8qqTgdq:edit",
    "attributes": {
      "resource_type": "creation",
      "resource_id": "D8qqTgdq",
      "operation": "edit",
      "permission": false
    }
  }
}

Abilities are usually included in the meta section of responses from other API endpoints.

If needed though, specific abilities can be requested through this endpoint.

Request

GET /v2/abilities/:id

Params

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Ability details

Attributes

Attribute Type null? Description
resource_type String no
resource_id String no
operation String no name of ability that was checked
permission Bool no true if current user can perform the operation

Possible operations

Creations

For creations, the possible operations are:

Operation Description
edit allowed to edit this creation
report allowed to report this creation
see_reflection_text allowed to see reflection text (description)
see_reflection_video allowed to see reflection video (soon to be deprecated)
share allowed to being shared

Galleries

For galleries, the possible operations are:

Operation Description
edit allowed to edit this gallery
share allowed to being shared
submit_to allowed to submit creations to this gallery

Users

For users, the possible operations are:

Operation Description
edit allowed to edit this user
switch allowed to switch to this user
switch_without_password allowed to switch to this user without password
share allowed to being shared
customize allowed to customize this user

Accounts

For accounts, the possible operations are:

Operation Description
edit allowed to edit this user
switch allowed to switch to this user
share allowed to being shared
customize allowed to customize this user
share_fully share all resources via social media

Comments

For comments, the possible operations are:

Operation Description
report allowed to report this comment
decline allowed to decline this comment
approve allowed to approve this report
delete allowed to delete this comment

Bubbles

For comments, the possible operations are:

Operation Description
destroy allowed to delete this bubble

Sharing resources

Requesting share_fully abilities:

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X GET https://api.creatubbles.com/v2/abilities/all:share_fully

Response:

{
  "data": {
    "type": "abilities",
    "id": "all:share_fully",
    "attributes": {
      "resource_type": "all",
      "resource_id": null,
      "operation": "share_fully",
      "permission": true
    }
  }
}

Each sharable resource has share ability returned in its meta. You also can retrieve this information via specific ability request but if you want to share resource via social media, you need to combine this information with ability to share_fully, which is defined per logged in user.

As it is specified per current logged in user it doesn’t require the resource_id to be provided in the request. You need to provide all as resource_type though.

Operation Description Included in meta for
share_fully share via social networks Accounts

Activities

List activities

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X GET https://api.creatubbles.com/v2/activities

Response

{
  "data":[{
    "type":"activities",
    "id":"",
    "attributes":{
    },
    "relationships":{
      "user":{
        "data":{ "id":"xUt6Feou","type":"users" }
      },
    }
  }]
}

Retrieves activities from the site. The activities returned by this endpoint correspond to the activities listed under the “For you” section of the web site.

Requests

Get recommended activities

GET /v2/activities

Get activities created on a user’s profile

GET /v2/users/:user_id/activities

Get activities created on a gallery

GET /v2/galleries/:gallery_id/activities

params

By default you receive recommended activities for the current user. You can use a resource type and resource id to get only activities added on this resource.

Name Description Required
user_id filter activities on user false
gallery_id filter activities on gallery false

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Activity details

Attributes

Attribute Type null? Description
id String no
key String no type of activity, see below
count Int no number of activities
items_count Int no number of items (related creations / comments / bubbles)
created_at Time no
last_updated_at Time no

Relationships

Name # Object null? Description
owners n User no users which triggered this activity
creation 1 Creation yes for activities on creation
gallery 1 Gallery yes for activities on gallery
user 1 User yes for activities on user
related_creations n Creation yes related creations (see above for details)
related_comments n Comment yes related comments (see above for details)

Possible activity types (key)

creation.bubbled

Bubble(s) on creations.

creation.commented

Comment(s) on a creation.

creation.published

Creation was published.

Bubble(s) on galleries.

Comment(s) on a gallery.

Creation(s) where added to a gallery.

user.bubbled

Bubble(s) on users.

user.commented

Comment(s) on a user.

Users

List user’s creators or managers

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X GET https://api.creatubbles.com/v2/users?user_id=c54lks2dj&scope=managers

Response

{
  "data": [{
    "type":"users",
    "id":"ektSdqhS",
    "attributes":{
      "username": "Aichan",
      "display_name": "Aichan",
      "list_name":"Aichan (@Aichan)",
      "name": "Aichan",
      "role": "creator",
      "age": "1y 8m",
      "gender": "unknown",
      "country_code": "JP",
      "country_name": "Japan",
      "avatar_url": "https://d1x1kv7c0y4dpg.cloudfront.net/users/19/creations/4409/matrix_view_retina/1418657645creation.jpg",
      "short_url": "https://ctbl.es/Aichan",
      "added_bubbles_count":3,
      "activities_count":15,
      "bubbles_count":2,
      "comments_count":0,
      "creations_count":71,
      "creators_count":1,
      "galleries_count":0,
      "managers_count":2,
      "last_bubbled_at":null,
      "last_commented_at":null,
      "signed_up_as_instructor":false,
      "what_do_you_teach":null,
      "interests":null,
      "home_schooling":false,
      "created_at": "2014-09-29T09:22:56.047Z",
      "updated_at": "2014-09-29T09:22:56.047Z"
    },
    "relationships":{
      "school": {"data": null},
      "custom_style": {"data":{"id": "1","type":"custom_styles"}
      }
    }
  }]
}

Requests

Get current user’s creators:

GET /v2/users (deprecated)

GET /v2/users/me/creators

Get current user’s managers:

GET /v2/users?scope=managers (deprecated)

GET /v2/users/me/managers

Get current user’s ‘My Connections’:

GET /v2/users/me/connected_users

Get users followed by current user:

GET /v2/users/me/followed_users

Get current user’s creators by group:

GET /v2/groups/:group_id/creators

Get user’s creators:

GET /v2/users?user_id=:user_id (deprecated)

GET /v2/users/:user_id/creators

Get user’s managers:

GET /v2/users?user_id=:user_id&scope=managers (deprecated)

GET /v2/users/:user_id/managers

Get user’s 'My Connections’:

GET /v2/users/:user_id/connected_users

Get users followed by a user:

GET /v2/users/:user_id/followed_users

Get users available for user switching:

GET /v2/user_switch/users

Params

All optional

Name Options Default Description
user_id id of user (or me) for which managers or creators are requested - lists users (creators or managers) for the specified user
group_id id of group - list creators in this group
scope either managers or creators, default: creators (deprecated) false
sort “display_name”, “age”, “created_at” “display_name” prepend - for descending order

Filtering results

All of user list endpoints allows filtering and searching users.

Search users

To search users you need to pass query parameter

GET /v2/users?query=test GET /v2/users/:user_id/managers?query=test

Apply filters

We support JsonAPI format for filtering resources. That means, you should nest filters in filter key, for example: /users?filter[role]=instructor

You can use params below to filter results.

Name Type Description
group String name of group to filter by
location String the country name or code
role String allowed values: creator, instructor, parent
school String name of school to filter by

Included

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Get user’s profile

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X GET https://api.creatubbles.com/v2/users/D8qqTgdq

Response:

{
  "meta":{
    "abilities":[{
      "id":"user:D8qqTgdq:customize",
      "type":"abilities",
      "relationships":{},
      "attributes":{
        "resource_type":"user",
        "resource_id":"D8qqTgdq",
        "permission":true,
        "operation":"customize"
      }
    }]
  },
  "data":{
    "type":"users",
    "id":"D8qqTgdq",
    "attributes": {
      "username":"peter",
      "display_name":"Peter",
      "list_name":"Peter (@peter)",
      "name":"peter",
      "role":"parent",
      "age":"",
      "gender":"unknown",
      "country_code":"BE",
      "country_name":"Belgium",
      "avatar_url":"https://d2uq42xcenkqo0.cloudfront.net/users/3/creations/17477/matrix_view_retina/1446077378creation.jpg",
      "short_url":"http://ctbl.es/peter",
      "added_bubbles_count":690,
      "activities_count":1887,
      "bubbles_count":2,
      "comments_count":0,
      "creations_count":158,
      "creators_count":3,
      "galleries_count":2,
      "managers_count":1,
      "last_bubbled_at":"2015-10-16T03:09:42.027Z",
      "last_commented_at":null,
      "signed_up_as_instructor":false,
      "what_do_you_teach":null,
      "interests":null,
      "home_schooling":false,
      "created_at":"2013-05-29T07:09:38.505Z",
      "updated_at":"2015-10-16T03:09:42.027Z"
    },
    "relationships": {
      "school":{"data":null},
      "custom_style":{"data":null}
    }
  }
}

Request

GET /v2/users/:id

Params

Included

Included

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Get ID Of current User

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X GET https://api.creatubbles.com/v2/users/me

You can easly retrive information about current logged in user by passing /me as user id in the get user request.

Create Creator

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X POST "https://api.creatubbles.com/v2/creators" \
  -d '{
      "data":{
        "type": "user",
        "attributes": {
          "name": "MrWolf",
          "birth_year": "2005",
          "birth_month": "12",
          "country": "CH",
          "gender": "unknown"
        }
      }
    }'

Response:

{
  "data":{
    "type":"users",
    "id":"D8qqTgdq",
    "attributes": {
      "username":"peter",
      "display_name":"Peter",
      "list_name":"Peter (@peter)",
      "name":"peter",
      "role":"parent",
      "age":"",
      "gender":"unknown",
      "country_code":"BE",
      "country_name":"Belgium",
      "avatar_url":"https://d2uq42xcenkqo0.cloudfront.net/users/3/creations/17477/matrix_view_retina/1446077378creation.jpg",
      "short_url":"http://ctbl.es/peter",
      "added_bubbles_count":690,
      "activities_count":1887,
      "bubbles_count":2,
      "comments_count":0,
      "creations_count":158,
      "creators_count":3,
      "galleries_count":2,
      "managers_count":1,
      "last_bubbled_at":"2015-10-16T03:09:42.027Z",
      "last_commented_at":null,
      "signed_up_as_instructor":false,
      "what_do_you_teach":null,
      "interests":null,
      "home_schooling":false,
      "created_at":"2013-05-29T07:09:38.505Z",
      "updated_at":"2015-10-16T03:09:42.027Z"
    },
    "relationships": {
      "school":{"data":null},
      "custom_style": {"data":null}
    }
  }
}

Request

POST /v2/creators

Attributes

Name Description Required
name unique name (max size: 15 characters) true
display_name publicly visible name false
birth_year integer between 1900 and [last year] e.g.: 2005 false
birth_month integer between 1 and 12 false
country e.g.: PL, UK, CH, etc. false
gender string value (‘unknown’)

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Destroy creator

Request with flat params

curl \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.api+json' \
  -X DELETE https://api.creatubbles.com/v2/creators/xdjlk78JH

Correct - no content (204):

You can remove managed creator, if you have correct permissions to do it (see: abilities section) for more details.

Requests

DELETE /v2/users/:user_id

Params

Name Description Required
user_id id of user you want to remove true

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Create multiple creators

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X POST "https://api.creatubbles.com/v2/creator_builder_jobs" \
  -d '{
      "data":{
        "type": "creator_builder_jobs",
        "attributes": {
          "birth_year": 2005,
          "amount": 10,
          "group": "Class 1"
        }
      }
    }'

Response:

  "data":{
    "type":"creator_builder_jobs",
    "id": "12211",
    "attributes": {
      "amount": 10,
      "group": "Class 1",
      "birth_year": 2005,
      "created_at":"2013-05-29T07:09:38.505Z",
      "updated_at":"2015-10-16T03:09:42.027Z"
    },
   "meta": []
  }

Request

POST /v2/creator_builder_jobs

Attributes

Name Type Description Required
amount Integer the amount of creators to add true
birth_year Integer integer between 1900 and [last year] e.g.: 2005 true
group String group to add creators to false

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

User details

Attributes

Attribute Type null? Description
id String no
username String no
display_name String no
list_name String no this is based on user’s username and display_name
name String no
role String no role is set at signup and can be either ‘creator’, 'parent’ or 'instructor’
age String yes age is counted based on birth_year and birth_month
gender String no 'unknown’ deprecated
country_code String yes
country_name String yes
avatar_url String yes
short_url String no this is based on username
added_bubbles_count Int no
activities_count Int no number of activities on this user
bubbles_count Int no number of bubbles this user received
comments_count Int no number of comments this user received
creations_count Int no number of creations the user created
creators_count Int no number of creators
galleries_count Int no number of galleries the user created
managers_count Int no number of managers for this user
last_bubbled_at Time yes
last_commented_at Time yes
signed_up_as_instructor Bool no
what_do_you_teach String yes profile: What do you teach? (Teachers only)
interests String yes profile: Interests (Teachers only)
home_schooling Bool yes
created_at Time no
updated_at Time no

Please note that the user object itself can’t be changed. You can create new managed creators through the Creator endpoint and change it through the Account object / endpoints.

Relationships

Name # Object null? Description
school 1 School yes
custom_style 1 CustomStyle yes

User Custom Styles

Get user’s custom_style

curl \
  -H 'Accept: application/vnd.api+json'
  -X GET https://api.creatubbles.com/v2/users/ocFsl3l2/custom_style

Response

{
  "data": {
    "id": "3893",
    "type": "custom_styles",
    "attributes": {
      "name": null,
      "header_background_id": "pattern3",
      "body_background_id": "pattern0",
      "font": null,
      "bio": null,
      "body_colors": [
        "#C0C0C0",
        "#DD1F26",
        "#BC2025"
      ],
      "header_colors": [
        "#C0C0C0",
        "#FFFFFF"
      ],
      "body_creation_url": "https://d3fll5fltyv3n9.cloudfront.net/users/1/creations/1/list_view_retina/1457373creation.jpg",
      "header_creation_url": null,
      "created_at": "2016-05-30T11:08:23.346Z",
      "updated_at": "2016-05-30T15:45:26.305Z"
    },
    "relationships": {
      "user": {
        "data": {
          "id": "ocFsl3l2",
          "type": "users"
        }
      },
      "header_creation": {
        "data": {
          "id": "Skl11MST",
          "type": "creations"
        }
      },
      "body_creation": {
        "data": {
          "id": "Skl11MST",
          "type": "creations"
        }
      }
    }
  }
}

Requests

Get specific user’s custom style:

GET /v2/users/:user_id/custom_style

Access Restrictions

Possible responses

Success:

Errors:

Note: For error messages description, see: Error Messages Section

Update Custom Style

Request

PUT /users/:user_id/custom_style

Params

Name Description Required
user_id The id of user to be styled true

Set creation as background

As creation_url isn’t an editable field, you can’t change this attribute to set creation as background. There is other way to do it though. Each custom style has its own related creation objects to be shown as header or body background. It can be specified as relation.


curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X PUT https://api.creatubbles.com/v2/users/xdjlk78JH/custom_style \
  -d '{ data: { \
    type: "custom_styles", \
    attributes: { \
      "header_background_id": 'pattern1', \
      "header_colors": ["#fff", "#000", "#abc"], \
      "body_background_id: "pattern0", \
    }, \
    relationships: {
      "body_creation": { "data": { "id": "lkj3V4hg" } }
    }
  } }'

Attributes

See Custom style details for possible attributes / relations.

Custom style details

Attributes

Attribute Type null? editable Description
id String no no
name String no yes CSS style for custom name: deprecated
header_background_id String yes yes This is id of styling pattern used in header section of user’s profile. Possible values: ‘patternX’, where 'X’ is a number. For example 'pattern0’ is responsible for creation background, 'pattern1’ and greater describes the css patterns.
body_background_id String yes yes See above. Id of styling pattern used in body section of user’s profile.
font String yes yes Font name that user can use to present it’s name
bio String yes yes The short sentence described the profile
body_colors Array yes yes The array of colors used in choosen header pattern. For example: ’[ “#C0C0C0”, “#DD1F26”, “#BC2025” ]’
header_colors Array yes yes The array of colors used in choosen body pattern. For example: ’[ “#C0C0C0”, “#DD1F26”, “#BC2025” ]’
body_creation_url String yes no The url of creation assigned to the custom style if pattern0 is set fot body_background_id.
header_creation_url String yes no The url of creation assigned to the custom style if pattern0 is set fot header_background_id.
created_at DateTime no no
updated_at DateTime no no

Relationships

Name # Object null? editable Description
user 1 User no no the customized profile
header_creation 1 Creation yes yes creation used as header background
body_creation 1 Creation yes yes creation used as body background

User Avatars

The URL to a user’s avatar is also included in each user object. This set of endpoints is for changing the avatar.

Update user’s avatar

Request

PUT /v2/users/:user_id/user_avatar

Params

Name Description Required
user_id user ID (use me for current user) true

Attributes

See Avatar details for possible attributes / relations.

User Avatar details

Attributes

Attribute Type null? editable Description
id String no no
avatar_url String yes no The user’s current avatar URL
pending_avatar_url String yes no in case the user’s avatar is from a pending creation, it’s not generally visible yet
created_at Time no no
updated_at Time no no

Relationships

Name # Object null? editable Description
avatar_creation 1 Creation yes yes the creation to use as the user’s avatar
avatar_suggestion 1 AvatarSuggestion yes yes the avatar suggestion to use as user’s avatar

Note: you can only either set avatar_creation or avatar_suggestion. To get a list of possible avatar suggestions, use the Avatar suggestions API.

Get suggested avatars

This will return a list of avatar suggestions.

Request

GET /v2/avatar_suggestions

Avatar Suggestions details

Attributes

Attribute Type null? Description
id String no
url String no URL to avatar image

Account data

The account endpoints allow you to get and update private user data, which is not exposed through the user object.

Get account data

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X GET https://api.creatubbles.com/v2/users/D8qqTgdq/account

Response:

{
  "data":{
    "type":"accounts",
    "id":"D8qqTgdq",
    "attributes": {
      "username":"peter",
      "display_name":"Peter",
      "name":"peter",
      "email":"info@creatubbles.com",
      "role":"parent",
      "birth_month":null,
      "birth_year":null,
      "age_display_type":"decade",
      "gender":"unknown",
      "ui_locale":"en",
      "pending_avatar_url":null,
      "password_updated_at":"2016-03-18T03:09:42.027Z",
      "group_list":[],
      "owned_tags":[],    
      "preapprove_comments":true,
      "receive_notifications":true,
      "what_do_you_teach":"",
      "interests":"",
      "managed_creators_count":6,
      "country_code":"BE",
      "created_at":"2013-05-29T07:09:38.505Z",
      "update_at":"2016-03-18T03:09:42.027Z"
    }
  }
}

Retrieve the user’s public and private data. The account object will have the same ID as the user.

Request

GET /v2/users/:user_id/account

Params

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Update account data

Request

PUT /v2/users/:user_id/account

Params

Name Description Required
user_id user ID true

Attributes

See Account details for possible attributes / relations.

To link user with the school, you need to send a put request to the accounts endpoint passing a school as relationship in the params. See: Account details for more information.

Request with flat params

curl \
  -H 'Accept: application/vnd.api+json' \
  -X PUT https://api.creatubbles.com/v2/users/xdjlk78JH/account \
  -d '{ "school": { "name": "Test", country_code: "BE" } }'

Request with json API params

curl \
  -H 'Accept: application/vnd.api+json' \
  -X PUT https://api.creatubbles.com/v2/users/xdjlk78JH/account \
  -d '{"data": {"relationships": { "school": { "data": { "attributes": { "name": "Test", country_code: "BE" } } } } } }'

You can use flat params or JSON API format.

Request

PUT /v2/users/:user_id/account

Attributes

Name Description Required
name name of added school true
country_code the code of country the school belongs to true

Create new password change

Request

POST /v2/users/:user_id/password_change

Params

Name Description Required
user_id user ID true

Attributes

Name Description Required
password new password to be set true
current_password the actual valid password false for managed creators
password_confirmation string, need to be identical with password false

Request with flat params

curl \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/users/xdjlk78JH/password_change \
  -d '{ "password": 'secret' }'

Request with json API params

curl \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/users/xdjlk78JH/password_change \
  -d '{"data": { "attributes": { "password": "secret"} } }'

You can use flat params or JSON API format.

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Account details

Attributes

Attribute Type null? editable Description
id String no no
username String no yes
display_name String no yes
name String no yes
email String yes yes Can be null only for young creators when they create their profiles.
birth_year Int yes yes > 1900
birth_month Int yes yes
age_display_type String no yes how to show the users age, can be either ‘detailed’, 'decade’ or 'dontshow’
gender String no no 'unknown’ deprecated
ui_locale String no yes locale for UI, 'en’ or 'ja’
pending_avatar_url String yes no in case the user’s avatar is from a pending creation, it’s not generally visible yet
group_list String[] yes no list of groups the user is a member of
owned_groups String[] yes no list of groups the user created
preapprove_comments Bool no yes pre-approve comments by managed creators
what_do_you_teach String yes yes profile: What do you teach?
interests String yes yes profile: Interests
managed_creators_count Int no no number of managed creators
country_code String yes yes
receive_notifications Bool no yes receive notifications
newsletter Bool no yes receive newsletter
password_updated_at Time yes no
current_sign_in_at Time yes no
created_at Time no no
updated_at Time no no

Relationships

Name # Object null? editable Description
user 1 User no no the corresponding user object
user_identifications n UserIdentification yes no
avatar_creation 1 Creation yes yes the creation to use as the user’s avatar (deprecated, see User Avatar API)
school 1 School yes yes the school to link user to

Update Account Example: update ui_locale

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X PUT https://api.creatubbles.com/v2/users/cab412/account \
  -d '{"data": {"type": "accounts", "attributes": { "ui_locale": "ja" } } }'

Update Account Example: update display_name

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X PUT https://api.creatubbles.com/v2/users/cab412/account \
  -d '{"data": {"type": "accounts", "attributes": { "display_name": "John Matrix" } } }'

Creations

List creations

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X GET https://api.creatubbles.com/v2/creations?sort=recent

Response

{
  "data":[{
    "type":"creations",
    "id":"YNzO8Rmv",
    "attributes":{
      "name":"Spaghetti stop motion",
      "approved":true,
      "approval_status":"approved",
      "created_at_age":"at 9 ~ 14y",
      "created_at_age_per_creator": {
        "oCRxzp9F": "at 14y",
        "vff379a2": "at 9y"
      },
      "reflection_text":null,
      "reflection_video_url":null,
      "image":{
        "links": {
          "original": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/original/1429754584creation.jpg",
          "full_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/full_view/1429754584creation.jpg",
          "list_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/list_view_retina/1429754584creation.jpg",
          "list_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/list_view/1429754584creation.jpg",
          "matrix_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/matrix_view_retina/1429754584creation.jpg",
          "matrix_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/matrix_view/1429754584creation.jpg",
          "gallery_mobile": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/gallery_mobile/1429754584creation.jpg",
          "explore_mobile": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/explore_mobile/1429754584creation.jpg",
          "share": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/share/1429754584creation.jpg"
        }
      },
      "image_status":3,
      "bubbles_count":6,
      "comments_count":0,
      "views_count":138,
      "last_bubbled_at":"2015-05-06T02:46:10.557Z",
      "last_commented_at":null,
      "last_submitted_at":"2015-04-23T02:02:40.450Z",
      "short_url":"https://ctbl.es/YNzO8Rmv",
      "obj_file_url": "https://d3fll5fltyv3n9.cloudfront.net/users/25523/creations/25326/1456735918creation/3d_objects/obj/Hatch.obj",
      "play_iframe_url": "/shade3d_objects/YNzO8Rmv",
      "created_at":"2015-04-23T02:02:40.161Z",
      "updated_at":"2015-04-23T02:02:40.161Z"
    },
    "relationships":{
      "user":{
        "data":{ "id":"xUt6Feou","type":"users" }
      },
      "creators":{
        "data":[{ "id":"xUt6Feou","type":"users"}]
      }
    }
  }]
}

Requests

List recent creations:

GET /v2/creations

List creations submitted to gallery:

GET /v2/creations?gallery_id=YNzO8Rmv #deprecated

GET /v2/galleries/:gallery_id/creations

List creations by user:

GET /v2/creations?user_id=YNzO8Rmv #deprecated

GET /v2/users/:user_id/creations

List creations by partner_application:

GET /v2/creations?partner_application_id=slug #deprecated

GET /v2/partner_applications/:partner_application_id/creations

Lookup creations by name:

GET /v2/creations?search=dog #deprecated

GET /v2/creations?query=dog

List recommended creations by creation:

GET /v2/creations/:creation_id/recommended_creations

List recommended creations added by user:

GET /v2/users/:user_id/recommended_creations

List filtered creations creations:

GET /v2/creations?only_public=true #deprecated

GET /v2/creations?filter[public]=true

Params

Name Description Required
gallery_id if given, specific gallery’s creations are downloaded if accessible false
user_id if given, specific user’s creations are downloaded if accessible false
partner_application_id if given, specific partner app’s creations are downloaded if accessible false
search keyword to filter creations by name false
creation_id used in /recommended_creations, which returns recommendations for this creation false
only_public boolean, used in any scope, filters only approved creations false

Filters

All filters should be nested in filter key, for example: /v2/creations?filter[public]=true

Name Description Format
age creations created at specific age object including keys: (from, to). age[from]=10&age[to]=15
has_video list creations with of without videos boolean
ids only creations with ids included array
location name of code of country creations was added in string
public filter only public creations boolean
school name of school creation was created in string

Included

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Get specific creation

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X GET https://api.creatubbles.com/v2/creations/YNzO8Rmv

Response

{
  "links": {
    "self": "https://api.creatubbles.com/v2/creations/YNzO8Rmv"
  },
  "data":{
    "type":"creations",
    "id":"YNzO8Rmv",
    "attributes":{
      "name":"Spaghetti stop motion",
      "approved":true,
      "approval_status": "approved",
      "created_at_age":"at 9 ~ 14y",
      "tags":["tag1","tag2","tag3"],
      "created_at_age_per_creator": {
        "oCRxzp9F": "at 14y",
        "vff379a2": "at 9y"
      },
      "reflection_text":null,
      "reflection_video_url":null,
      "image":{
        "links": {
          "original": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/original/1429754584creation.jpg",
          "full_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/full_view/1429754584creation.jpg",
          "list_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/list_view_retina/1429754584creation.jpg",
          "list_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/list_view/1429754584creation.jpg",
          "matrix_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/matrix_view_retina/1429754584creation.jpg",
          "matrix_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/matrix_view/1429754584creation.jpg",
          "gallery_mobile": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/gallery_mobile/1429754584creation.jpg",
          "explore_mobile": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/explore_mobile/1429754584creation.jpg",
          "share": "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/share/1429754584creation.jpg"
        }
      },
      "image_status":3,
      "content_type":"image/jpg",
      "bubbles_count":6,
      "comments_count":0,
      "views_count":138,
      "last_bubbled_at":"2015-05-06T02:46:10.557Z",
      "last_commented_at":null,
      "last_submitted_at":"2015-04-23T02:02:40.450Z",
      "short_url":"https://ctbl.es/YNzO8Rmv",
      "obj_file_url": "https://d3fll5fltyv3n9.cloudfront.net/users/25523/creations/25326/1456735918creation/3d_objects/obj/Hatch.obj",
      "play_iframe_url": "/shade3d_objects/YNzO8Rmv",
      "created_at":"2015-04-23T02:02:40.161Z",
      "updated_at":"2015-04-23T02:02:40.161Z"
    },
    "relationships":{
      "user":{
        "data":{ "id":"xUt6Feou","type":"users" },
        "links":{ "self":"https://api.creatubbles.com/v2/users/xUt6Feou"}
      },
      "creators":{
        "data":[{ "id":"xUt6Feou","type":"users"}]
      }
    }
  }
}

Request

GET /v2/creations/:id

Params

Included

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Create creation

Request with flat params

curl \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/creations \
  -d '{ "name" : "Test", "tags" : ["tag1","tag2","tag3"], "creator_ids": ['l2kYi3i9'] }'

Request with params in JsonAPI format

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/creations' \
  -d '{ "data": { \
        "type": "creations", \
        "attributes": { "name" : "Test", "tags" : ["tag1","tag2","tag3"] }, \
        "relationships": { \
          "creators": { "data": ["type": "users", "id": 'l2kYi3i9'] } \
        } } \
      }'

Correct - created creation (201):

{
  "links": {
    "self": "https://api.creatubbles.com/v2/creations/YNzO8Rmv"
  },
  "data":{
    "type":"creations",
    "id":"YNzO8Rmv",
    "attributes":{
      "name":"Untitled",
      "approved":false,
      "approval_status":"unapproved",
      "tags":["tag1","tag2","tag3"],
      "created_at_age":"at 9 ~ 14y",
      "created_at_age_per_creator": {
        "oCRxzp9F": "at 14y",
        "vff379a2": "at 9y"
      },
      "image": null,
      "image_status":1,
      "bubbles_count":0,
      "comments_count":0,
      "views_count":0,
      "last_bubbled_at":null,
      "last_commented_at":null,
      "last_submitted_at":null,
      "short_url":"https://ctbl.es/YNzO8Rmv",
      "created_at":"2015-04-23T02:02:40.161Z"
    },
    "relationships":{
      "user":{
        "data":{ "id":"xUt6Feou","type":"users" },
        "links":{ "self":"https://api.creatubbles.com/v2/users/xUt6Feou"}
      },
      "creators":{
        "data":[{ "id":"xUt6Feou","type":"users"}]
      }
    }
  }
}

To create creation with custom attributes set, you can send a request with params provided in two ways.

Just use flat params like is shown in first request, or do it with JsonAPI format.

Request

POST /v2/creations

This request will return new created creation object with ID you can use in next steps.

Attributes

See Creation details for possible attributes / relations.

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Update creation

Request

PUT /creations/:id

Params

Name Description Required
id creation ID true

Attributes

See Creation details for possible attributes / relations.

Destroy creation

Request with flat params

curl \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.api+json' \
  -X DELETE https://api.creatubbles.com/v2/creations/xlkf2a78JH

Correct - no content (204):

You can remove creations, if you have correct permissions to do it (see: abilities section) for more details.

Requests

DELETE /v2/creations/:creation_id

Params

Name Description Required
creation_id id of creation you want to approve true

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Creation details

Attributes

Attribute Type null? editable Description
id String no no
name String no yes
translated_names Array no no Array of name translation objects, see below
approved Bool no no depracated
approval_status String no no Possible values: “approved”, “unapproved”, “rejected”
created_at_age String yes no
created_at_age_per_creator Hash no no This is the hash of ids of creators related to creation with proper ages assigned. It’s very useful for listing creators with information about how old it was when creation have been added
reflection_text String yes yes user’s “reflection” / “comment” about the creation
reflection_video_url String yes yes link to video on creation process, has to be a valid URL
image.links.original String yes no original file as uploaded (usually don’t use this)
image.links.full_view String yes no suitable for fullscreen view, original aspect ratio
image.links.list_view String yes no 300x300 (might be cropped)
image.links.list_view_retina String yes no 600x600 (might be cropped)
image.links.matrix_view String yes no 105x105 (might be cropped)
image.links.matrix_view_retina String yes no 210x210 (might be cropped)
image.links.gallery_mobile String yes no max 300x600
image.links.explore_mobile String yes no 90x90 (might be cropped)
image.links.share String yes no 600x600 (might be cropped)
image_status Int no no 1: “empty”; 2: “processing”; 3: “ready”
content_type String no no Content’s Mime Type or name of external content service (e.g. "image/jpg", "youtube", "video/mp4", "application/zip")
bubbles_count Int no no
comments_count Int no no
views_count Int no no
last_bubbled_at Time yes no
last_commented_at Time yes no
last_submitted_at Time yes no
short_url String no no
obj_file_url String yes no obj file for 3d object
play_iframe_url String yes no url to 3d player which can be embedded in iframe
tags Array yes yes array of tags
created_at Time no no
updated_at Time no no

Name translation objects

Attribute Type null? Description
code String no language code
name String no name in given language
original Bool no whether this is the original entered by user (true) or translated (false) version

Setter attributes

The following attributes are only used to set a value when creating or updating objects. They are not returned by the API.

Attribute Type null? Description
created_at_month Int yes setter for created_at_age, e.g. 12
created_at_year Int yes setter for created_at_age, e.g. 2014

Relationships

Name # Object null? editable Description
user 1 User no no the uploader
creators n User no yes
partner_application 1 PartnerApplication yes no present if this creation was uploaded through a partner application

Toyboo! creation details

For Toyboo! creations we offer type specific details. This API endpoint is only available for Tobyoo! creations.

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X GET https://api.creatubbles.com/v2/creations/YNzO8Rmv/toyboo_details

Response

{
  "links": {
    "self": "https://api.creatubbles.com/v2/creations/YNzO8Rmv/toyboo_details"
  },
  "data":{
    "type":"creation_toyboo_details",
    "id":"YNzO8Rmv",
    "attributes":{
      "uzpb_url":"https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/1429754584creation.uzpb",
      "content_url":"https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/1429754584creation/content.json"
    }
  }
}

Request

GET /v2/creations/:id/toyboo_details

Params

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Creation Upload

Overview of upload process

The uploading process involves a couple of API calls. This is the general process to follow:

  1. Login user to get access token
  2. Create a new creation (no content yet) - see Creations#create
  3. Create creation’s upload object - see CreationUpload#create
  4. Upload the file using the details from previous step - see upload the file
  5. Notify API that upload finished - see CreationUpload#update
  6. Get upload to get processing image status updates - see CreationUpload#show

Create creation upload

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X POST https://api.creatubbles.com/v2/creations/YNzO8Rmv/uploads'

Response for created upload:

{
  "links": {
    "self": "https://api.creatubbles.com/v2/creations/YNzO8Rmv/uploads"
  },
  "data":{
    "type":"uploads",
    "id":"30891",
    "attributes":{
      "url": "https://s3.amazon.com/link/to/upload/your/image",
      "ping_url": "https://api.creatubbles.com/v2/uploads/63582",
      "created_at":"2015-04-23T02:02:40.161Z",
      "content_type":"image/jpg"
    },
    "relationships":{
      "creation":{
        "data":{ "id":"YNzO8Rmv","type":"creations" },
        "links":{ "self":"https://www.creatubbles.com.com/api/v2/creations/YNzO8Rmv"}
      }
    }
  },
  "included": []
}

This will return all information required to upload a new image. You can use this also to upload updated versions of a creation.

Request

POST /v2/creations/:creation_id/uploads

Custom file types

By default we assume that you upload image/jpg files. In case you are uploading different files, you need to add the extension of the file you intend to uploaded to your request when creating the upload object.

Params

Name Allowed extensions
extension Image: png, jpg, jpeg
Video: h264, mpeg4, wmv, webm, flv, ogg, ogv, mp4, m4v, f4v, mov
Compound: zip (see compound format)

See also: Supported file formats

Returned object

As result, you’ll get back a creation’s upload object, which includes all the details you need to upload the file in the next step:

Name Description
url upload your file to this URL (see next step)
content_type Use this as Content-Type header for your upload request.
ping_url ping this URL after the upload finished (see next next step)

Upload the file

Use the URL we returned in the previous step to do the actual upload. Use a PUT request to the given URL with the image or video in the body.

Uploading an image

curl \
  -H 'Content-Type: image/jpg' \
  -H 'Accept: application/vnd.api+json' \
  -T summer-girl.jpg \
  -X PUT "https://creatubbles.s3.amazonaws.com/creation-b0dytPrT?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAICWC3JU5LBQJOB5A%2F20151221%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20151221T161913Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=a01b09d04d6a7da228b931e5a0e35d7465f274df602ed1ff8ba"

Uploading a video

curl \
  -H 'Content-Type: video/quicktime' \
  -H 'Accept: application/vnd.api+json' \
  -T summer-girl-video.mov \
  -X PUT "https://creatubbles.s3.amazonaws.com/creation-b0dytPrT?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAICWC3JU5LBQJOB5A%2F20151221%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20151221T161913Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=a01b09d04d6a7da228b931e5a0e35d7465f274df602ed1ff8ba"

Request

PUT :upload_url

Headers

Name Description
Content-Type To properly upload a file, you have to include the Content-Type header as provided in the previous step. If this header is not included, your upload request will be denied.

Update creation upload

​curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer 4aec18d02527e83d56b87c8a995f3f0fdee4cbc4bd0ad5bd1d0957699b65649f' \
  -X PUT https://api.creatubbles.com/v2/uploads/63582

Response: 204 No Content

After uploading the creation file, use the ping_url parameter given when you created the creation upload to notify the API server that the upload was completed.

Request

PUT /v2/uploads/:id

Params

name type description
id the upload id

Attributes

name type description
aborted_with string argument included when upload fails; include the body returned by the failed upload attempt or ‘user’ in case the user aborted the upload

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Get creation upload

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X GET https://api.creatubbles.com/v2/uploads/30891

After informing server that upload is finished (previous step), it starts processing the uploaded file.

You can request the upload object to get updates on the processing, including if errors occur (which can be useful during development). We’ll also include the creation object itself in this response, so you don’t have to request updates for it separately.

Request

GET /v2/uploads/:id

Params

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Changes you can observe

Upload completed

Creation is now being processed.

Processing completed

Creation can now be viewed on the web (but usually is still pending review).

Processing failure

Creation can now be viewed on the web (but usually is still pending review).

Creation upload details

Attributes

Attribute Type null? editable Description
id String no no
url String yes no URL to use for file uploads; only present for uploads which aren’t complete yet
content_type String no no File content type
ping_url String no no URL to ping after upload completed or failed
completed_at Time yes no set when ping URL was called
aborted Bool no no true if upload or processing failed
aborted_with String yes yes indicates why upload/processing failed
processing_completed Bool no no true after processing finished
processing_details Object yes no details on processing, e.g. on failure
created_at Time no no
updated_at Time no no

Relationships

Name # Object null? editable Description
creation 1 Creation no no

Supported file formats

Images

We support: png, jpeg

Videos

We support: h264, mpeg4, wmv, webm, flv, ogg, ogv, mp4, m4v, f4v, mov

3D objects

We support: obj (see compound format)

Picture books

We support: uzpb (Toyboo! picture book format)

Compound format

Example manifest.json:

{
  "format": "v1",
  "application": {
    "name": "MagicalSketch 3D",
    "version": "3.0.1",
    "platform": "Mac OS X 10.11.3"
  },
  "title": "MagicalSketch Sample",
  "description": "MagicalSketch Sample description",
  "previewImage": "sample.jpg",
  "objects": [
    {
      "type": "obj",
      "file": "obj/sample.obj",
      "background": "obj/background.jpg",
      "additional": [ "obj/sample.mtl", "obj/texture_1.png" ]
    },
    {
      "type": "stl",
      "file": "sample.stl"
    },
    {
      "type": "s3d",
      "file": "sample.s3d",
      "native": true,
      "version": "3.0.2"
    },
  ],
  "exportedAt": "2016-02-19T12:33:23+01:00",
  "contentRevision": "1"
}

Content for this zip would be:

manifest.json
sample.jpg
sample.stl
sample.s3d
obj/sample.obj
obj/sample.mtl
obj/texture_1.png

We use our compound file format to upload creations which are composed of several files, like 3D creations.

The compound file format is a ZIP file which contains a manifest.json. This manifest.json explains the contents of the ZIP file, so it can be processed by us.

Structure of manifest.json

Notes on objects:

Notes for preview images:

Image Manipulations

Update creation image

Request

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X PUT https://api.creatubbles.com/v2/creations/xdjlk78JH/image_manipulation \
  -d '{ data: { \
          type: "image_manipulations", \
          attributes: { \
            rotation: 90, \
            cropping: {
              x: 150,
              y: 0,
              width: 100,
              height: 111
            } \
          } \
        } \
      }'

Response: 204 No Content

Except reuploading images we provide a lot of customization options to add rotation, cropping and some visual effects to actual uploaded image.

To do this, you need to generate put request to image_manipulation endpoint, and apply your changes.

Request

PUT /v2/creations/:creation_id/image_manipulation

Params

Name Description Required
creation_id creation ID true

Attributes

See Image Manipulation details for possible attributes / relations.

Image manipulation details

Attributes

Attribute Type null? editable Description
id String no no
rotation Integer yes yes Dagrees to rotate the image by. Allows values in: (0, 90, 180, 270)
cropping Object yes yes Hash of values to crop the image

Cropping

The cropping is a json object with four attributes included:

"cropping": {
  "x": 100,
  "y": 100,
  "width": 150,
  "height": 150
}

Attributes

Attribute Type null? editable Description
x Integer yes yes the x position of the top left corner of the cropping.
y Integer yes yes the y position of the top left corner of the cropping.
width Integer yes yes the width of the cropping.
height Integer yes yes the height of the cropping

All values if not set, are interpreted as current image dimensions, which means:

Relationships

Name # Object null? editable Description
creation 1 Creation no no the corresponding creation object

Galleries

List galleries

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X GET https://api.creatubbles.com/v2/galleries

Response:

{
  "data": [{
    "type": "galleries",
    "id": "xdjlk78JH",
    "attributes": {
      "name": "Test Gallery",
      "description": "Test Gallery's description",
      "open_for_all":false,
      "banner": {
        "links": {
          "original": "https://d1x1kv7c0y4dpg.cloudfront.net/users/3907/creations/6943/1429681194creation.jpg",
          "list_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/3907/creations/6943/list_view_retina/1429681194creation.jpg",
          "list_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/3907/creations/6943/list_view/1429681194creation.jpg",
          "matrix_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/3907/creations/6943/matrix_view_retina/1429681194creation.jpg",
          "matrix_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/3907/creations/6943/matrix_view/1429681194creation.jpg",
          "explore_mobile": "https://d1x1kv7c0y4dpg.cloudfront.net/users/3907/creations/6943/explore_mobile/1429681194creation.jpg"
        }
      },
      "preview_image_urls":[
        "https://d1x1kv7c0y4dpg.cloudfront.net/users/3907/creations/6943/matrix_view_retina/1429681194creation.jpg",
        "https://d1x1kv7c0y4dpg.cloudfront.net/users/3918/creations/6943/matrix_view_retina/1429681853creation.jpg",
        "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/matrix_view_retina/1429754584creation.jpg",
        "https://d1x1kv7c0y4dpg.cloudfront.net/users/3920/creations/6961/matrix_view_retina/1429750892creation.jpg"
      ],
      "creations_count":4,
      "bubbles_count":0,
      "comments_count":0,
      "last_bubbled_at":null,
      "last_commented_at":null,
      "short_url":"http://ctbl.es/HC5VdsBM",
      "created_at": "2014-09-04T14:51:29Z",
      "updated_at": "2014-09-04T14:51:29Z"
    },
    "relationships": {
      "owner": {
        "data": { "type": "users", "id": "aklLkj23lk" },
        "links": { "self": "https://api.creatubbles.com/v2/users/aklLkj23lk" }
      }
    }
  }]
}

Requests

Get public galleries:

GET /v2/galleries

GET /v2/galleries?sort=recent

Get featured galleries:

GET /v2/featured_galleries

Get galleries owned or collaborated by a user:

GET /v2/galleries?user_id=:user_id (deprecated)

GET /v2/users/:user_id/galleries

Get galleries shared or owned by current user:

GET /v2/users/me/galleries

GET /v2/users/me/galleries?filter=:gallery_filter

Get user’s favorite galleries:

GET /v2/users/me/favorite_galleries

Get galleries of a creation:

GET /v2/creations/:creation_id/galleries

Params

Name Description Required
sort includes: [:popular, :recent (default)] false
user_id valid user ID, lists the galleries owned by given user (use me for current user) false
creation_id valid creation ID, lists the creation’s galleries false
gallery_filter possible filters:
only_owned: only list galleries this user created;
only_shared: only list galleries shared with the user (only available for own users)
false

Notes:

Filtering results

All of galleries list endpoints allows filtering and searching galleries.

Search galleries

To search galleries by name you need to pass query parameter

GET /v2/galleries?query=test GET /v2/users/:user_id/galleries?query=test

Apply filters

We support JsonAPI format for filtering resources. That means, you should nest filters in filter key, for example: /v2/galleries?filter[location]=US

You can use params below to filter results.

Name Type Description
location String the country name or code
shared_with UserId only galleries collaborated by user
owned_by UserId only galleries owned by user

Included

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X GET https://api.creatubbles.com/v2/galleries/1gl34d4

Response:

{
  "links": {
    "self": "https://api.creatubbles.com/v2/galleries/xdjlk78JH"
  },
  "data": {
    "type": "galleries",
    "id": "xdjlk78JH",
    "attributes": {
      "name": "Test Gallery",
      "description": "Test Gallery's description",
      "open_for_all":false,
      "banner": {
        "links": {
          "original": "https://d1x1kv7c0y4dpg.cloudfront.net/users/3907/creations/6943/1429681194creation.jpg",
          "list_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/3907/creations/6943/list_view_retina/1429681194creation.jpg",
          "list_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/3907/creations/6943/list_view/1429681194creation.jpg",
          "matrix_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/3907/creations/6943/matrix_view_retina/1429681194creation.jpg",
          "matrix_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/3907/creations/6943/matrix_view/1429681194creation.jpg",
          "explore_mobile": "https://d1x1kv7c0y4dpg.cloudfront.net/users/3907/creations/6943/explore_mobile/1429681194creation.jpg"
        }
      },
      "preview_image_urls":[
        "https://d1x1kv7c0y4dpg.cloudfront.net/users/3907/creations/6943/matrix_view_retina/1429681194creation.jpg",
        "https://d1x1kv7c0y4dpg.cloudfront.net/users/3918/creations/6943/matrix_view_retina/1429681853creation.jpg",
        "https://d1x1kv7c0y4dpg.cloudfront.net/users/4419/creations/6963/matrix_view_retina/1429754584creation.jpg",
        "https://d1x1kv7c0y4dpg.cloudfront.net/users/3920/creations/6961/matrix_view_retina/1429750892creation.jpg"
      ],
      "creations_count":4,
      "bubbles_count":0,
      "comments_count":0,
      "last_bubbled_at":null,
      "last_commented_at":null,
      "short_url":"http://ctbl.es/HC5VdsBM",
      "created_at": "2014-09-04T14:51:29Z",
      "updated_at": "2014-09-04T14:51:29Z"
    },
    "relationships": {
      "owner": {
        "data": { "type": "users", "id": "aklLkj23lk" },
        "links": { "self": "https://api.creatubbles.com/v2/users/aklLkj23lk" }
      }
    }
  }
}

Request

GET /v2/galleries/:id

Params

Included

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Request with flat params

curl \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/galleries \
  -F name="My gallery" \
  -F description="Test description" \
  -F owner_id=aklLkj23lk

Request with params in jsonAPi format

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/galleries \
  -d '{ data: { \
          type: "galleries", \
          attributes: { \
            name: 'Test gallery name', \
            description: 'Test gallery description', \
            open_for_all: 1 \
          }, \
          relationships: { \
            owner: { \
              data: { \
                type: "users", id: 'aklLkj23lk' \
              } \
            } \
          } \
        } \
      }'

Response:

{
  "links": {
    "self": "https://api.creatubbles.com/v2/galleries/xdjlk78JH"
  },
  "data": {
    "type": "galleries",
    "id": "xdjlk78JH",
    "attributes": {
      "name": "Test Gallery",
      "description": "Test Gallery's description",
      "open_for_all":false,
      "banner":null,
      "preview_image_urls":[],
      "creations_count":0,
      "bubbles_count":0,
      "comments_count":0,
      "last_bubbled_at":null,
      "last_commented_at":null,
      "short_url":"http://ctbl.es/HC5VdsBM",
      "created_at": "2014-09-04T14:51:29Z",
      "updated_at": "2014-09-04T14:51:29Z"
    },
    "relationships": {
      "owner": {
        "data": { "type": "users", "id": "aklLkj23lk" },
        "links": { "self": "https://api.creatubbles.com/v2/users/aklLkj23lk" }
      }
    }
  }
}

To create a new gallery only a name is required. As owner, the current user is assumed.

If a gallery for a managed creator as the owner should be created, you need to supply the user ID of the managed creator when creating the gallery.

You can use flat params or JSON API format.

Request

POST /v2/galleries

Attributes

See Gallery details for possible attributes / relations.

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Request with flat params

curl \
  -H 'Accept: application/vnd.api+json' \
  -X PUT https://api.creatubbles.com/v2/galleries/xdjlk78JH \
  -F name="My gallery" \
  -F description="Test description"

Request with params in jsonAPi format

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X PUT https://api.creatubbles.com/v2/galleries/xdjlk78JH \
  -d '{ data: { \
          type: "galleries", \
          attributes: { \
            name: 'Test gallery name', \
            description: 'Test gallery description', \
            open_for_all: 1 \
          } \
        } \
      }'

Response: 204 No Content

This updates an existing gallery.

You can use flat params or JSON API format.

Request

PUT /v2/galleries/:id

Params

Name Description Required
id valid gallery ID true

Attributes

See Gallery details for possible attributes / relations.

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Attributes

Attribute Type null? editable Description
id String no no
name String no yes
description String yes yes
open_for_all Bool no yes everyone can submit creations
banner.links.original String yes no
banner.links.list_view String yes no
banner.links.list_view_retina String yes no
banner.links.matrix_view String yes no
banner.links.matrix_view_retina String yes no
banner.links.explore_mobile String yes no
preview_image_urls String[] yes no
creations_count Int no no
bubbles_count Int no no
comments_count Int no no
last_bubbled_at Time yes no
last_commented_at Time yes no
short_url String no no
created_at Time no no
updated_at Time no no

Relationships

Name # Object null? editable Description
owner 1 User no only when creating new gallery gallery owner
partner_application 1 PartnerApplication yes no present if this gallery belongs to a partner application

Request with flat params

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X POST https://api.creatubbles.com/v2/gallery_submissions
  -d '{ "gallery_id" : "Xlk3jTR2", "creation_id": ":LKJ3lkj2" }'

Request with params in jsonAPi format

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/gallery_submissions \
  -d '{ data: { \
          relationships: { \
            gallery: { \
              data: { \
                type: "galleries", id: 'Xlk3jTR2' \
              } \
            }, \
            creation: { \
              data: { \
                type: "creations", id: 'LKJ3lkj2' \
              } \
            } \
          } \
        } \
      }'

Response:

{
  "data": {
    "id": "13",
    "type": "gallery_submissions",
    "relationships": {
      "gallery": {
        "data": { "id": "Xlk3jTR2", "type": "galleries" }
      },
      "creation": {
        "data": { "id": "LKJ3lkj2", "type": "creations" }
      }
    }
  }
}

To submit creation into the gallery, you need to be authenticated user, and you need to be able to create submissions.

Just use flat params like is shown in first request, or do it with JsonAPI format.

Request

POST /v2/gallery_submissions

Attributes

Name Description Required
gallery_id Gallery to submit true
creation_id Creation submitted true

Access Restrictions

You can submit into:

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Contents

List content

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X GET https://api.creatubbles.com/v2/contents/recent

Response:

{
  "data": [{
    "type": "contents",
    "id": "creation-123",
    "attributes": {
      "type": "creation"
    },
    "relationships": {
      "creation": {
        "data": { "type": "creations", "id": "aklLkj23lk" }
      },
      "gallery": {"data": null},
      "user": {"data": null}
    }
  }]
}

This response lists mixed contents, delivers users, creations and galleries in one list.

Requests

Search content:

GET /v2/contents?query=:query

List recent content:

GET /v2/contents/recent

List trending content:

GET /v2/contents/trending

List contents based on ‘My Connections’

GET /v2/contents/connected

List contents based on followed users

GET /v2/contents/followed

List contents by a user

GET /v2/users/:user_id/contents

List contents bubbled by a user

GET /v2/users/:user_id/bubbled_contents

Params

Name Description
query text user entered for searching
user_id a valid user ID

Included

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Bubbles

It is possible for users to bubble creations, galleries and other users. Bubbling expresses appreciation for the bubbled content by that user.

List bubbles

Bubbles on a creation

curl -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer 1lk23h4567gjkl87nmgfsdzi6' \
  -X GET https://api.creatubbles.com/v2/creations/YNzO8Rmv/bubbles

Response

{
  "data": [
    {
      "type":"bubbles",
      "id":"1",
      "attributes":{
        "x_pos":3,
        "y_pos":4,
        "random_pos":false,
        "color":"green",
        "color_hex":"#95d903",
        "created_at":"2015-04-23T02:02:40.161Z"
      },
      "relationships":{
        "bubbler":{
          "data":{ "id":"xUt6Feou","type":"users" }
        },
        "creation":{
          "data":{ "id":"YNzO8Rmv","type":"creations"}
        }
      }
    }
  ]
}

Bubbles on a gallery

curl -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer 1lk23h4567gjkl87nmgfsdzi6' \
  -X GET https://api.creatubbles.com/v2/galleries/xdjlk78JH/bubbles

Response

{
  "data": [
    {
      "type":"bubbles",
      "id":"1",
      "attributes":{
        "created_at":"2015-04-23T02:02:40.161Z"
      },
      "relationships":{
        "bubbler":{
          "data":{ "id":"xUt6Feou","type":"users" }
        },
        "gallery":{
          "data":{ "id":"xdjlk78JH","type":"galleries"}
        }
      }
    }
  ]
}

Bubbles on a user

curl -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer 1lk23h4567gjkl87nmgfsdzi6' \
  -X GET https://api.creatubbles.com/v2/users/aklLkj23lk/bubbles

Response

{
  "data": [
    {
      "type":"bubbles",
      "id":"1",
      "attributes":{
        "created_at":"2015-04-23T02:02:40.161Z"
      },
      "relationships":{
        "bubbler":{
          "data":{ "id":"xUt6Feou","type":"users" }
        },
        "user":{
          "data":{ "id":"aklLkj23lk","type":"users"}
        }
      }
    }
  ]
}

Retrieves bubbles for the given creation / gallery / user.

Bubbles on creations have additional fields for a position and a color of a bubble. This is used to show an actual bubble on the given position with the given color on top of the creation.

Requests

GET /v2/creations/:creation_id/bubbles

GET /v2/galleries/:gallery_id/bubbles

GET /v2/users/:user_id/bubbles

Params

Name Description Required
creation_id valid creation ID when listing bubbles on a creation
gallery_id valid gallery ID when listing bubbles on a gallery
user_id valid user ID when listing bubbles on a user
order the way you want to order bubbles. String: “asc” or “desc” false

Order

The default bubbles order is by newest first. You can reverse it by adding ?order=desc in your request.

Included

Access Restrictions

Possible responses

Success:

Create bubble

Request with flat params

curl \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/creations/YNzO8Rmv/bubbles \
  -d '{ "color" : "orange", "x_pos" : 0.10, "y_pos" : 0.20 }'

Correct - created bubble (201):

{
  "data": {
    "type":"bubbles",
    "id":"1",
    "attributes":{
      "x_pos":0.10,
      "y_pos":0.20,
      "random_pos":false,
      "color":"orange",
      "color_hex": "#f58416",
      "created_at":"2016-03-16T10:55:40.161Z"
    },
    "relationships":{
      "bubbler":{
        "data":{ "id":"xUt6Feou","type":"users" }
      },
      "creation":{
        "data":{ "id":"YNzO8Rmv","type":"creations"}
      }
    }
  }
}

Creates a new bubble for the given creation / gallery / user.

Bubbles on creations have additional fields for a position and a color of a bubble. This is used to show an actual bubble on the given position with the given color on top of the creation. In case no position or color is given when creating a new bubble on a creation, those values will be randomly assigned.

Requests

POST /v2/creations/:creation_id/bubbles

POST /v2/galleries/:gallery_id/bubbles

POST /v2/users/:user_id/bubbles

Params

Name Description Required
creation_id valid creation ID when creating comment on a creation
gallery_id valid gallery ID when creating comment on a gallery
user_id valid user ID when creating comment on a user

Attributes

Name Description Required
color (string, only for creations) bubble color, one of ‘gray’, 'blue’, 'pink’, 'red’, 'green’, or 'orange’ no
x_pos (float, only for creations) bubble x position, 0 < x_pos < 1 no
y_pos (float, only for creations) bubble y position, 0 < y_pos < 1 no

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Update a bubble

Request with flat params

curl \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/bubbles/1 \
  -d '{ "color" : "blue" }'

Response: 204 No Content

Updates an existing bubble. This will only make sense on creation bubbles, and this only allows to change the color of the bubble at the moment.

Requests

PUT /v2/bubbles/:id

Params

Name Description Required
id valid bubble ID true

Attributes

Name Description Required
color (string) bubble color, one of ‘gray’, 'blue’, 'pink’, 'red’, 'green’, or 'orange’ true

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Delete a bubble

Request

curl \
  -H 'Accept: application/vnd.api+json' \
  -X DELETE https://api.creatubbles.com/v2/bubbles/1

Response: 204 No Content

Deletes an existing bubble.

Requests

DELETE /v2/bubbles/:id

Params

Name Description Required
id valid bubble ID true

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Bubble Colors

We support a range of colors for bubbles.

Request

curl -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer eecc03848ed5431631f257c7c8' \
  -X GET https://api.creatubbles.com/v2/bubbles/colors

Response

{
  "data": [
    {
      "id": "1",
      "type": "bubble-colors",
      "attributes": {
        "color": "gray",
        "color_hex": "#aaaaaa"
      }
    },
    {
      "id": "2",
      "type": "bubble-colors",
      "attributes": {
        "color": "blue",
        "color_hex": "#15b8f5"
      }
    },
    {
      "id": "3",
      "type": "bubble-colors",
      "attributes": {
        "color": "pink",
        "color_hex": "#ff09eb"
      }
    },
    {
      "id": "4",
      "type": "bubble-colors",
      "attributes": {
        "color": "red",
        "color_hex": "#de0000"
      }
    },
    {
      "id": "5",
      "type": "bubble-colors",
      "attributes": {
        "color": "green",
        "color_hex": "#95d903"
      }
    },
    {
      "id": "6",
      "type": "bubble-colors",
      "attributes": {
        "color": "orange",
        "color_hex": "#f58416"
      }
    },
  ]
}

When the user creates a new bubble on a creation, the user can choose an optional color for their bubble. In case no color is specified for a creation bubble, we will assign a random color.

Please use the colors provided here to present the user a selection of possible colors for their bubble. Use the color as color when creating a new bubble or when updating a bubble. Use the given color_hex to display the color to the user.

We don’t expect the colors to change often, so feel free to cache the results of this API call.

Request

GET /v2/bubbles/colors

Params

None

Access Restrictions

Possible responses

Success:

Comments

It is possible for users to post comments on creations, galleries and other users.

List comments

Comments on a creation

curl -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer 1lk23h4567gjkl87nmgfsdzi6' \
  -X GET https://api.creatubbles.com/v2/creations/YNzO8Rmv/comments

Response

{
  "data": [
    {
      "type":"comments",
      "id":"1",
      "attributes":{
        "text":"very nice colors!",
        "approved":true,
        "created_at":"2015-04-23T02:02:40.161Z",
        "commentable_type":"Creation"
      },
      "relationships":{
        "commenter":{
          "data":{ "id":"xUt6Feou","type":"users" }
        },
        "creation":{
          "data":{ "id":"YNzO8Rmv","type":"creations"}
        }
      }
    }
  ]
}

Comments on a gallery

curl -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer 1lk23h4567gjkl87nmgfsdzi6' \
  -X GET https://api.creatubbles.com/v2/galleries/xdjlk78JH/comments

Response

{
  "data": [
    {
      "type":"comments",
      "id":"1",
      "attributes":{
        "text":"very nice gallery",
        "approved":true,
        "created_at":"2015-04-23T02:02:40.161Z",
        "commentable_type":"Gallery"
      },
      "relationships":{
        "commenter":{
          "data":{ "id":"xUt6Feou","type":"users" }
        },
        "gallery":{
          "data":{ "id":"xdjlk78JH","type":"galleries"}
        }
      }
    }
  ]
}

Comments on a user

curl -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer 1lk23h4567gjkl87nmgfsdzi6' \
  -X GET https://api.creatubbles.com/v2/users/aklLkj23lk/comments

Response

{
  "data": [
    {
      "type":"comments",
      "id":"1",
      "attributes":{
        "text":"awesome profile",
        "approved":true,
        "created_at":"2015-04-23T02:02:40.161Z",
        "commentable_type":"User"
      },
      "relationships":{
        "commenter":{
          "data":{ "id":"xUt6Feou","type":"users" }
        },
        "user":{
          "data":{ "id":"aklLkj23lk","type":"users"}
        }
      }
    }
  ]
}

Retrieves comments for the given creation / gallery / user.

Requests

GET /v2/creations/:creation_id/comments

GET /v2/galleries/:gallery_id/comments

GET /v2/users/:user_id/comments

Params

Name Description Required
creation_id valid creation ID when listing comments on a creation
gallery_id valid gallery ID when listing comments on a gallery
user_id valid user ID when listing comments on a user

Included

Access Restrictions

Possible responses

Success:

Create comment

Request with flat params

curl \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/creations/YNzO8Rmv/comments \
  -d '{ "text" : "Really nice!" }'

Correct - created comment (201):

{
  "data": [
    {
      "type":"comments",
      "id":"2",
      "attributes":{
        "text":"Really nice!",
        "approved":false,
        "created_at":"2016-03-16T08:47:40.161Z",
        "commentable_type":"Creation"
      },
      "relationships":{
        "commenter":{
          "data":{ "id":"xUt6Feou","type":"users" }
        },
        "creation":{
          "data":{ "id":"YNzO8Rmv","type":"creations"}
        }
      }
    }
  ]
}

Creates a new comment for the given creation / gallery / user.

Requests

POST /v2/creations/:creation_id/comments

POST /v2/galleries/:gallery_id/comments

POST /v2/users/:user_id/comments

Params

Name Description Required
creation_id valid creation ID when creating comment on a creation
gallery_id valid gallery ID when creating comment on a gallery
user_id valid user ID when creating comment on a user

Attributes

Name Description Required
text (string) true

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Approve comment

Request with flat params

curl \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/comments/1234/approval

Correct - updated comment (204):

{
  "data": [
    {
      "type":"comments",
      "id":"1234",
      "attributes":{
        "text":"Really nice!",
        "approved":true,
        "created_at":"2016-03-16T08:47:40.161Z",
        "commentable_type":"Creation"
      },
      "relationships":{
        "commenter":{
          "data":{ "id":"xUt6Feou","type":"users" }
        },
        "creation":{
          "data":{ "id":"YNzO8Rmv","type":"creations"}
        }
      }
    }
  ]
}

You can approve comment, if you have correct permissions to do it (see: abilities section) for more details.

Requests

POST /v2/comments/:comment_id/approval

Params

Name Description Required
comment_id id of comment you want to approve true

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Decline comment

Request with flat params

curl \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.api+json' \
  -X DELETE https://api.creatubbles.com/v2/comments/1234/approval

Correct - no content (204):

You can decline comment, if you have correct permissions to do it (see: abilities section) for more details.

Requests

DELETE /v2/comments/:comment_id/approval

Params

Name Description Required
comment_id id of comment you want to decline true

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Landing URLs

Landing URLs are used to retrieve application and user specific URLs for various landing pages on the creatubbles website.

List landing URLs

User not signed in, using your client credential

curl -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer eecc03848ed5431631f257c7c8' \
  -X GET https://api.creatubbles.com/v2/landing_urls

Response

{
  "data": [
    {
      "id": "ctb-about_us",
      "type": "landing_urls",
      "attributes": {
        "url": "https://www.creatubbles.com/more/about_us"
      }
    },
    {
      "id": "ctb-terms_of_use",
      "type": "landing_urls",
      "attributes": {
        "url": "https://www.creatubbles.com/more/terms_of_use"
      }
    },
    {
      "id": "ctb-privacy_policy",
      "type": "landing_urls",
      "attributes": {
        "url": "https://www.creatubbles.com/more/privacy_policy"
      }
    },
    {
      "id": "ctb-registration",
      "type": "landing_urls",
      "attributes": {
        "url": "https://www.creatubbles.com/signup"
      }
    },
    {
      "id": "ctb-forgot_password",
      "type": "landing_urls",
      "attributes": {
        "url": "https://www.creatubbles.com/user/password/new"
      }
    },
    {
      "id": "ctb-explore",
      "type": "landing_urls",
      "attributes": {
        "url": "https://www.creatubbles.com/activity"
      }
    }
  ]
}

User signed in, using user credentials

curl -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer 1lk23h4567gjkl87nmgfsdzi6' \
  -X GET https://api.creatubbles.com/v2/landing_urls

Response

{
  "data": [
    {
      "id": "ctb-about_us",
      "type": "landing_urls",
      "attributes": {
        "url": "https://www.creatubbles.com/more/about_us"
      }
    },
    {
      "id": "ctb-terms_of_use",
      "type": "landing_urls",
      "attributes": {
        "url": "https://www.creatubbles.com/more/terms_of_use"
      }
    },
    {
      "id": "ctb-privacy_policy",
      "type": "landing_urls",
      "attributes": {
        "url": "https://www.creatubbles.com/more/privacy_policy"
      }
    },
    {
      "id": "ctb-user_profile",
      "type": "landing_urls",
      "attributes": {
        "url": "https://www.creatubbles.com/users/X2s4KaL"
      }
    },
    {
      "id": "ctb-explore",
      "type": "landing_urls",
      "attributes": {
        "url": "https://www.creatubbles.com/activity"
      }
    }
  ]
}

Retrieve all landing URLs (besides creation landing URLs) for a specific application or user.

Use an application only access token to retrieve application specific URLs before a user signed in. Use the user access token after a user signed in to retrieve user specific URLs.

Request

GET /v2/landing_urls

Params

None

Access Restrictions

Possible responses

Success:

Common landing URLs (when using application only access token)

These URLs are not user specific, but application specific. The URLs in the example in the righthand side don’t include any application specific parameters for reasons of brevity.

Please note that URLs might change without notice.

The following landing URLs will be included in the response:

ID Description
ctb-about_us About Creatubbles page
ctb-terms_of_use Creatubbles terms of use
ctb-privacy_policy Creatubbles privacy policy
ctb-registration For new user onboarding
ctb-forgot_password For users who forgot their password
ctb-explore Starting page to explore Creatubbles

User landing URLs (when using user access token)

These landing URLs will pass along the user’s authentication from the app to the website. So if a user is already signed into the application, they don’t need to sign in again when accessing the website through the given URL.

The URLs in the example in the righthand side don’t include any user specific parameters for reasons of brevity.

We recommend not storing the landing URLs for too long as the credentials in the URL might get invalidated. Ideally refresh them whenever the user wants to access an URL. Or refresh once after each restart.

The following landing URLs will be included in the response:

ID Description
ctb-about_us About Creatubbles page
ctb-terms_of_use Creatubbles terms of use
ctb-privacy_policy Creatubbles privacy policy
ctb-user_profile The user’s profile page
ctb-explore Starting page to explore Creatubbles
cte-account_dashboard Embeddable account dashboard
cte-upload_guidelines Embeddable upload guidelines

Get specific landing URL

curl -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer 1lk23h4567gjkl87nmgfsdzi6' \
  -X GET https://api.creatubbles.com/v2/landing_urls/ctb-user_profile

Response

{
  "data": {
    "id": "ctb-user_profile",
    "type": "landing_urls",
    "attributes": {
      "url": "https://www.creatubbles.com/users/X2s4KaL"
    }
  }
}

Use this to retrieve a specific landing URL. Please see the notes above for more details.

Request

GET /v2/landing_urls/:id

Params

Access Restrictions

Possible responses

Errors:

Success:

Get landing URL for creation

curl -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer 1lk23h4567gjkl87nmgfsdzi6' \
  -X GET https://api.creatubbles.com/v2/creations/YNzO8Rmv/landing_url

Response

{
  "data": {
    "id": "creation-YNzO8Rmv",
    "type": "landing_urls",
    "attributes": {
      "url": "https://www.creatubbles.com/creations/YNzO8Rmv"
    }
  }
}

Use this to retrieve a specific landing URL for a creation.

This is usually used after uploading a creation, to allow the user to jump to the Creatubbles website to see and adjust their creation there.

Request

GET /v2/creations/:creation_id/landing_url

Params

Access Restrictions

Possible responses

Errors:

Success:

Notifications

List notifications

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X GET https://api.creatubbles.com/v2/notifications

Response

{
  "data": [{
    "id":"ektSdqhS",
    "type":"notifications",
    "attributes":{
      "type": "new_submission",
      "created_at": "2014-09-29T09:22:56.047Z"
    },
    "relationships":{
      "bubble": {"data": null},
      "comment": {"data": null},
      "creation": {"data": null},
      "gallery_submission": {"data":{"id": "cnGeja7wn","type":"gallery_submissions"}
      }
    }}, {
    "id":"ektSdqh1",
    "type":"notifications",
    "attributes":{
      "type": "new_creation",
      "created_at": "2014-09-29T09:22:56.047Z"
    },
    "relationships":{
      "bubble": {"data": null},
      "comment": {"data": null},
      "creation": {"data":{"id": "cn2wGT3wu","type":"creations"},
      "gallery_submission": {"data": null}
      }
    }}, {
    "id":"ektSdqh2",
    "type":"notifications",
    "attributes":{
      "type": "bubbled_creation",
      "created_at": "2014-09-29T09:22:56.047Z"
    },
    "relationships":{
      "bubble": {"data":{"id": "1nG5ja7wn","type":"bubbles"},
      "comment": {"data": null},
      "creation": {"data": null},
      "gallery_submission": {"data": null}
      }
    }}, {
    "id":"ektSdqh3",
    "type":"notifications",
    "attributes":{
      "type": "new_comment",
      "created_at": "2014-09-29T09:22:56.047Z"
    },
    "relationships":{
      "bubble": {"data": null},
      "comment": {"data":{"id": "5nG1ja5wn","type":"comments"},
      "creation": {"data": null},
      "gallery_submission": {"data": null}
      }
    }
  }]
}

Requests

Get current user’s notifications:

GET /v2/notifications

Params

Name Description Required
filter filter notifications false

Available filters

Filter Description
bubbles Only notifications about received bubbles
comments_approved Only notifications about approved comments
comments_pending Only notifications about pending comments
comments_declined Only notifications about declined comments

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Additional data in meta

In addition to the pagination attributes, we also supply the following attributes in meta:

Name Description
total_unread_count total number of not seen notifications
total_new_count total number of notifications with flag is_new set to true. Those are notifications which details were not read yet.
last_viewed_at date when notifications were viewed

Read notification

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X POST https://api.creatubbles.com/v2/notifications/1/read

No Content (204)

Requests

Mark notification as read:

POST /v2/notifications/:id/read

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Track when notifications were viewed

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -X PUT https://api.creatubbles.com/v2/notifications/view_tracker \
  -d '{ viewed_all: true }'

No Content (204)

Requests

Track notifications viewed event:

PUT /v2/notifications/view_tracker

Attributes

Name Description Required
viewed_all false if users open notifications dropdown, true when they open all notifications view true

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Notification details

Attributes

Attribute Type null? editable Description
id String no no
type String no no type of notification
text String no no text for this notification; see also entities below on how to link up parts of this text.
short_text String no no short text to be used in the notification dropdown (no entities)
is_new Bool no no tells if notifications hasn’t been seen
created_at Time no no
updated_at Time no no

Relationships

Base relationships

Name # Object null? Description
creation 1 Creation yes
user 1 User yes
gallery 1 Gallery yes

Notifications are always for either a creation, user or gallery. So any notification will reference exactly one of those three objects.

The visual icon shown for a notification should be based on this base object.

Additional relationships

Name # Object null? Description
comment 1 Comment yes
gallery_submission 1 GallerySubmission yes

In addition to the base relationships, some notifications have additional relationships. Those are mainly used for the call to actions.

Entities

Name # Object null? Description
user_entities n UserEntity yes
creation_entities n CreationEntity yes
gallery_entities n GalleryEntity yes

The notification will also reference different entities, which are annotations to the notification’s text. The entities describe how parts of the notification text relate to other objects. Applications should highlight those parts of the text and allow the user to navigate to the linked objects.

Types

Name Included Objects Description
new_creation creation new creation published
bubbled_creation creation creation was bubbled
new_comment creation, comment new comment on a creation
user, comment new comment on a user
gallery, comment new comment on a gallery
followed_creator user new follower
new_submission gallery, gallery_submission new submission to a gallery
another_comment creation, comment another comment on a creation
user, comment another comment on a user
gallery, comment another comment on a gallery
multiple_creators_created user notification about user who added multiple creators

Entity details

Attributes

All entity types share the following attributes:

Attribute Type null? Description
id String no
start_index Int no The position of the first character in text this entity is describing
end_index Int no The position of the last character in text this entity is describing

Relationships

Depending on the entity type, they have different relationships:

User entity

Name # Object null? Description
user 1 User no

Creation entity

Name # Object null? Description
creation 1 Creation no

Creation entity

Name # Object null? Description
gallery 1 Gallery no

Groups

List groups

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X GET https://api.creatubbles.com/v2/groups

Response

{
  "data":[{
    "type":"groups",
    "id":31,
    "attributes":{
      "name":"Group 1",
      "slug":"group-1",
      "creators_count":2
    },
    "relationships": {
      "avatar_creation":{"data":null}
    }
  }]
}

Retrieves all the user’s groups. Groups are private to the user’s account.

Request

GET /v2/groups

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Get specific group

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X GET https://api.creatubbles.com/v2/groups/31

Response

{
  "data":{
    "type":"groups",
    "id":31,
    "attributes":{
      "name":"Group 1",
      "slug":"group-1",
      "creators_count":2
    },
    "relationships": {
      "avatar_creation":{"data":null}
    }
  }
}

Retrieves a specific group.

Request

GET /v2/groups/:id

Params

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Create group

Request with flat params

curl \
  -H 'Accept: application/vnd.api+json'
  -X POST https://api.creatubbles.com/v2/groups
  -F name="Group 2"

Request with params in jsonAPi format

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/groups \
  -d '{ data: { \
          type: "groups", \
          attributes: { \
            name: 'Group 2', \
          } \
        } \
      }'

Response:

{
  "data":{
    "type":"groups",
    "id":53,
    "attributes":{
      "name":"Group 2",
      "slug":"group-2",
      "creators_count":0
    },
    "relationships": {
      "avatar_creation":{"data":null}
    }
  }
}

To create a new group only a name is required.

You can use flat params or JSON API format.

Request

POST /v2/groups

Attributes

See Group details for possible attributes / relations.

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Update group

Request with flat params

curl \
  -H 'Accept: application/vnd.api+json'
  -X POST https://api.creatubbles.com/v2/groups/53
  -F name="Nice Group Name"

Request with params in jsonAPi format

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/groups \
  -d '{ data: { \
          type: "groups", \
          attributes: { \
            name: 'Nice Group Name', \
          } \
        } \
      }'

Response: 204 No Content

This updates an existing group.

You can use flat params or JSON API format.

Request

PUT /v2/groups/:id

Params

Attributes

See Group details for possible attributes / relations.

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Delete a group

Request

curl \
  -H 'Accept: application/vnd.api+json' \
  -X DELETE https://api.creatubbles.com/v2/groups/53

Response: 204 No Content

Deletes an existing group.

Requests

DELETE /v2/groups/:id

Params

Access Restrictions

Possible Responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Group details

Attributes

Attribute Type null? editable Description
id String no no
name String no yes
slug String no no
creators_count Int no no
avatar_url String yes no shortcut for getting URL to avatar image (based on avatar_creation)

Relationships

Name # Object null? editable Description
avatar_creation 1 Creation yes yes

Add creators to a group

Interim solution: To add or remove creators from a group, use the account data API. It includes the attribute group_list, which expects an array of group names. Any missing groups will be created on the fly.

Partner Applications

Search for Partner Applications

  curl -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer 1lk23h4567gjkl87nmgfsdzi6' \
  -X GET https://api.creatubbles.com/v2/partner_applications?query=example-app

Response

{
  "data": [{
    "id": "example-app",
    "type": "partner-applications",
    "attributes": {
      "name": "Example App",
      "slug": "example-app",
      "short_url": "https://ctbl.es/example-app",
      "header_bg": {
        "links": {
          "original": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459684838creation.jpg",
          "list_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459684838creation.jpg",
          "list_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459684838creation.jpg",
          "matrix_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459684838creation.jpg",
          "matrix_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459684838creation.jpg",
          "explore_mobile": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459684838creation.jpg"
        }
      },
      "body_bg": {
        "links": {
          "original": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459587920creation.jpg",
          "list_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459587920creation.jpg",
          "list_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459587920creation.jpg",
          "matrix_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459587920creation.jpg",
          "matrix_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459587920creation.jpg",
          "explore_mobile": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459587920creation.jpg"
        }
      },
      "owner_name": "Example App Owner",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque sollicitudin purus eu est lacinia, sit amet vehicula lorem pretium. Duis metus orci, fringilla id pharetra et, ultrices in velit. Suspendisse cursus augue nec sodales pretium. Donec nec lorem lorem. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Mauris ac mauris arcu. Phasellus blandit nisi non quam blandit consectetur. Nam vitae hendrerit tortor. Nulla vehicula tristique magna, ut varius nisl vehicula a. Morbi ac aliquet nisi, in tincidunt ipsum. Integer eget magna in quam ultrices ultricies. Vestibulum consequat vel massa at rhoncus.",
      "cta_logged_in_label": "Get this app!",
      "cta_logged_out_label": "Sign in first to get this app!",
      "reqeust_cta_for_youngsters": true,
      "cta_for_youngsters_label": "Request this app!!",
      "cta_href": "http://www.example.com/download.html",
      "categories": "Art, Design",
      "age": "from 4+",
      "languages": "English Japanese",
      "support": "[Ask for support](http://www.example.com/contact.html) [Official site](http://www.example.com)",
      "developers": "",
      "platforms": "For Windows, Mac OSX, iPhone iOS, iPad iOS.",
      "show_other_apps": true,
      "display_creations_nr": 7,
      "about_card_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque sollicitudin purus eu est lacinia, sit amet vehicula lorem pretium.",
      "meta_title": "example-app",
      "meta_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque sollicitudin purus eu est lacinia, sit amet vehicula lorem pretium.",
      "meta_keywords": "app, creativity, art projects, design",
      "meta_og_title": "example-app",
      "meta_og_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque sollicitudin purus eu est lacinia, sit amet vehicula lorem pretium.",
      "meta_og_type": "",
      "meta_og_image": "",
      "avatar_url": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459685512creation.jpg"
    }
  }]
}

Use this to search for Partner Applications.

Request

GET /v2/partner_applications?query=:query

Params

Access Restrictions

Possible responses

Errors:

Success:

Get specific Partner Application

  curl -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer 1lk23h4567gjkl87nmgfsdzi6' \
  -X GET https://api.creatubbles.com/v2/partner_applications/example-app

Response

{
  "data": {
    "id": "example-app",
    "type": "partner-applications",
    "attributes": {
      "name": "Example App",
      "slug": "example-app",
      "short_url": "https://ctbl.es/example-app",
      "video_ids": [...],
      "video_titles": [...],
      "image_urls": [...],
      "header_bg": {
        "links": {
          "original": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459684838creation.jpg",
          "list_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459684838creation.jpg",
          "list_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459684838creation.jpg",
          "matrix_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459684838creation.jpg",
          "matrix_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459684838creation.jpg",
          "explore_mobile": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459684838creation.jpg"
        }
      },
      "body_bg": {
        "links": {
          "original": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459587920creation.jpg",
          "list_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459587920creation.jpg",
          "list_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459587920creation.jpg",
          "matrix_view_retina": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459587920creation.jpg",
          "matrix_view": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459587920creation.jpg",
          "explore_mobile": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459587920creation.jpg"
        }
      },
      "owner_name": "Example App Owner",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque sollicitudin purus eu est lacinia, sit amet vehicula lorem pretium. Duis metus orci, fringilla id pharetra et, ultrices in velit. Suspendisse cursus augue nec sodales pretium. Donec nec lorem lorem. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Mauris ac mauris arcu. Phasellus blandit nisi non quam blandit consectetur. Nam vitae hendrerit tortor. Nulla vehicula tristique magna, ut varius nisl vehicula a. Morbi ac aliquet nisi, in tincidunt ipsum. Integer eget magna in quam ultrices ultricies. Vestibulum consequat vel massa at rhoncus.",
      "cta_logged_in_label": "Get this app!",
      "cta_logged_out_label": "Sign in first to get this app!",
      "reqeust_cta_for_youngsters": true,
      "cta_for_youngsters_label": "Request this app!!",
      "cta_href": "http://www.example.com/download.html",
      "categories": "Art, Design",
      "age": "from 4+",
      "languages": "English Japanese",
      "support": "[Ask for support](http://www.example.com/contact.html) [Official site](http://www.example.com)",
      "developers": "",
      "platforms": "For Windows, Mac OSX, iPhone iOS, iPad iOS.",
      "show_other_apps": true,
      "display_creations_nr": 7,
      "about_card_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque sollicitudin purus eu est lacinia, sit amet vehicula lorem pretium.",
      "meta_title": "example-app",
      "meta_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque sollicitudin purus eu est lacinia, sit amet vehicula lorem pretium.",
      "meta_keywords": "app, creativity, art projects, design",
      "meta_og_title": "example-app",
      "meta_og_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque sollicitudin purus eu est lacinia, sit amet vehicula lorem pretium.",
      "meta_og_type": "",
      "meta_og_image": "",
      "avatar_url": "https://d1x1kv7c0y4dpg.cloudfront.net/users/111/creations/222/full_view/1459685512creation.jpg"
    }
  }
}

Use this to retrieve a specific Partner Application.

Request

GET /v2/partner_applications/:id

Params

Access Restrictions

Possible responses

Errors:

Success:

Partner Application details

Attributes

Attribute Type null? Description
id String no
name String no
slug String no
short_url String no
header_bg.links.original String yes
header_bg.links.list_view_retina String yes
header_bg.links.list_view String yes
header_bg.links.matrix_view_retina String yes
header_bg.links.matrix_view String yes
header_bg.links.explore_mobile String yes
body_bg.links.original String yes
body_bg.links.list_view_retina String yes
body_bg.links.list_view String yes
body_bg.links.matrix_view_retina String yes
body_bg.links.matrix_view String yes
body_bg.links.explore_mobile String yes
owner_name String yes
owner_country String yes standard country codes or “GLOBAL”
description String (Markdown) yes
about_us_url String yes URL for “Visit our site” link
cta_logged_in_label String yes Call To Action button’s label (when user is logged in)
cta_logged_out_label String yes Call To Action button’s label (when user is logged out)
reqeust_cta_for_youngsters Boolean no Determines if CTA button should replaced by permission request button with custom label for <13 yo creators
cta_for_youngsters_label String yes Label for permision request button
cta_href String yes Call To Action button’s href
categories String yes
age String yes
languages String yes
support String (Markdown) yes
developers String (Markdown) yes
platforms String (Markdown) yes
show_other_apps Boolean no Determines if other apps of the owner section should be visible
display_creations_nr Integer yes Number of visible creations submitted to app’s gallery
about_card_text String (Markdown) yes
meta_title String yes
meta_description String yes
meta_keywords String yes
meta_og_title String yes
meta_og_description String yes
meta_og_type String yes
meta_og_image String yes
avatar_url String yes
created_at Time no
updated_at Time no

Relationships

Name # Object null? Description
gallery 1 Gallery no
user 1 User no User profile of application owner
related_apps n PartnerApplication yes Other apps from the same owner
app_screenshots n AppScreenshot yes

AppScreenshot Attributes (included)

Attribute Type null? Description
url String yes Url for screenshot image (empty in case of video)
is_video Boolean no false in case of image, true if this is a video
vid String yes YouTube/Vimeo video identifier
title String yes Title for popup which displays the video
provider String yes "youtube" or "vimeo"
position Integer no Determines asset position in “Screenshots & Videos” section

Reporting Resources

Create a report

Request with flat params

curl \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/users/lkajbk32/report \
  -F message="this is inappropriate!" \

Request with params in jsonAPi format

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X POST https://api.creatubbles.com/v2/galleries \
  -d '{ "data": { \
          "type": "galleries", \
          "attributes": { \
            "message": "this is inappropriate!" \
          } \
        } \
      }'

Response: 204 no content

There are several resources you can report: Gallery, User, Comment, Creation.

Requests

POST /v2/users/:user_id/report

POST /v2/creations/:creation_id/report

POST /v2/galleries/:galler_id/report

POST /v2/comments/:comment_id/report

Attributes

See Report details for possible attributes /relations.

Access Restrictions

Possible responses

Errors:

Note: For error messages description, see: Error Messages Section

Success:

Report details

Attributes

Attribute Type Null? editable Description
id Integer no no
message String no yes The message including report’s reason

Schools

List schools

Schools on a creation

curl -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer 1lk23h4567gjkl87nmgfsdzi6' \
  -X GET https://api.creatubbles.com/v2/schools?filter[name]=the&preferred_country=US

Response

{
  "data": [ {
    "id":"1",
    "type":"schools",
    "attributes": {
      "name":"The test school",
      "instructors_count":0,
      "avatar_url":"/assets/default_avatars/school.jpg",
      "custom_style_header": null,
      "country_code":"US",
      "country_name":"United States"
    }
  } ]
}

Retrieves schools

Requests

GET /v2/schools

Filters

You can provide a name filter schools by passing a hash filter containing proper filters in it. Available filters are listed below.

Filters

{ "filter": { "name": "The" } }
Name Description Required
name The string to retrive collection of schools with name including it false
id Array of ids to filter by false

Params

Name Description Required
preferred_country the country code of preferred country. When passed, schools from given country will be returned first false

Access Restrictions

Possible responses

Success:

View resources

Increment views count

Updates Creation/Gallery views count. Call this endpoint whenever the user viewed a Creation/Gallery. The view counter will be update once a day for a given user.

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X PUT https://api.creatubbles.com/v2/creation/xlkf2a78JH/view

PUT /creation/:creation_id/view

Params

Name Description Required
creation_id Creation ID true

Request for creation view

curl \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -X PUT https://api.creatubbles.com/gallery/xdjlk78JH/view

PUT /creation/:gallery_id/view

Params

Name Description Required
gallery_id Gallery ID true

Pagination

Creatubbles API provides a bunch of information for clients to consume. You can even find, that you recieve more than you need. For example in case of listing resources, you often don’t need to display a hundreds of records in one time. Because of that (and due to the load of the servers) we provide default pagination for requesting resources.

Extracting pagination informations

Information about pagination is provided in the meta and links of an API response. For example, let’s make a curl request to get list of user creators to find out how many pages and records can we extract.

curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -d '{
        "user_id": "c54lks2dj",
        "scope": "managers"
      }'
  -X GET https://api.creatubbles.com/v2/users

Response

{
  "data": [...],
  "meta": {
    "total_count": "98",
    "total_pages": 5,
    "per_page": 20,
    "current_page": 1
  },
  "links":{
    "self": "/v2/users?page=1&scope=managers&user_id=X7c3aBb1",
    "next": "/v2/users?page=2&scope=managers&user_id=X7c3aBb1",
    "last": "/v2/users?page=5&scope=managers&user_id=X7c3aBb1"
  },
  "included":[...]
}

As you can see, there are bunch of informations returned for each request. Inside of meta root there is information about total objects requested, current page and number of page. In links route there is information about self/next/prev/last/first request.

Each link includes per_page attribute set to recieve the proper set of objects.

name returned
self always
first always
last always
next unless last_page requested
prev unless first_page requested

Customizing Pagination

By default first page of records is returned with the MAX limit of objects listed. You can’t get more than MAX records at once, but you can list less. MAX limit for per_page is dependent of resource type.

Reasource Name MAX (default) per_page
Bubbles 100
Comments 20
Creations 20
Galleries 20
GallerySubmissions 20
Notifications 20
Users 20
curl \
  -H 'Content-Type: application/vnd.api+json'
  -H 'Accept: application/vnd.api+json'
  -d '{
        "user_id": "c54lks2dj",
        "scope": "managers",
        "per_page": 5,
        "page": 8
      }'
  -X GET https://api.creatubbles.com/v2/users

Response

{
  "data": [...],
  "meta": {
    "total_count": "98",
    "total_pages": 20,
    "per_page": 5,
    "current_page": 8
  },
  "links":{
    "self": "/v2/users?page=8&per_page=5&scope=managers&user_id=X7c3aBb1",
    "prev": "/v2/users?page=7&per_page=5&scope=managers&user_id=X7c3aBb1",
    "next": "/v2/users?page=9&per_page=5&scope=managers&user_id=X7c3aBb1",
    "first": "/v2/users?page=10&per_page=5&scope=managers&user_id=X7c3aBb1",
    "last": "/v2/users?page=20&per_page=5&scope=managers&user_id=X7c3aBb1"
  },
  "included":[...]
}

Params:

Name Description Required Default
page current page to load false 1
per_page number of records to be shown on each page. It should be <= 20. For per_page > 20 server returns only 20 records on page. false 20

Errors

The CTB API V2 uses the following error codes:

Kind of errors

    {
      "status": 401,
      "errors": [{
        "code": "unauthorized_request",
        "title": "You are not authorized to access this resource.",
        "source": "https://www.creatubbles.com/api/v12/users"
      }]
    }
    {
      "status": 403,
      "errors": [{
        "code": "forbidden_resource",
        "title": "You are not authorized to access this resource.",
        "source": "https://www.creatubbles.com/api/v2/galleries/slj1214pi"
      }]
    }
    {
      "status": 404,
      "errors": [{
        "title": "Not found",
        "detail": "Record not found.",
        "source": "https://www.creatubbles.com/api/v2/users/fdj34dl3"
      }]
    }
    {
      "status": 422,
      "errors": [{
        "code": "validation-error-invalid-password",
        "title": "Not acceptable",
        "detail": "password: can't be blank",
        "source": "https://www.creatubbles.com/api/v2/users"
      }]
    }
    {
      "status": 429,
      "errors": [{
        "title": "Too many requests",
        "detail": "You have sent too many requests in a given amount of time. It is intended for use with rate limiting schemes.",
        "source": "https://www.creatubbles.com/api/v2/users"
      }]
    }
Error Code Meaning
400 Bad request - you requested a resource which returned validation errors
401 Not authorized – Access Token is invalid
403 Forbidden – Accessing forbidden resources. When trying to access restricted area.
404 Not Found – When object in the database cannot be found.
406 Not Acceptable – You requested a format that isn’t json
422 Validation error - You try to create/update a resource with invalid params
429 Too Many Requests – You’re requesting too many kittens! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Change Log

Changes to the Creatubbles API

January 24th, 2017

January 3rd, 2017

November 23th, 2016

November 13th, 2016

Nov 12th, 2016

October 31th, 2016 🎃

October 26th, 2016

Activities listing filtering

September 23th, 2016

Added new endoints:

September 15th, 2016

September 6th, 2016

September 1st, 2016

August 29th, 2016

August 25th, 2016

August 19th, 2016

August 8th, 2016

August 4th, 2016

August 3rd, 2016

July 2016

June 2016

May 2016

April 2016

March