NAV
cURL

Introduction

API Endpoint: https://api.twine.fm

Welcome to the Twine API v1.

The Twine Platform connects your website or application with the creative community on Twine.

To create start building your application, you will need API access and a Twine account. When logged into Twine, you you can generate your client_id and client_secret in your settings here.

The API currently supports operations for projects, users, comments, credits, lists and messages.

If you notice any bugs or an issue, please let us know.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://api.twine.fm"
  -H "Authorization: Bearer ACCESS_TOKEN"

Make sure to replace ACCESS_TOKEN with your API key.

First you will need to obtain a client id and a client secret, to do so please you will need a Twine account. Once logged in, you you can generate a client id and a client secret in your settings here. Once you have the client id and client secret, you can use them to obtain an access token which can be used with the API.

The Callback URL is address you wish to redirect a user after Authentication. When Requesting Authorization, the redirect_uri should match your Callback URL.

Twine expects the access token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer ACCESS_TOKEN

Token Lifetimes

Access tokens are short lived: 2 hours
Refresh tokens are long lived: 1 week

Grant Types:

Grant types need to be assigned to your application and this will be done as part of the application review process.

Grant Type Description
authorization_code Ask for user authorization
refresh_token Get an access token using the refresh token
client_credentials Get an access token for your own clients user

Scopes

Scopes need to be assigned to your application and this will be done as part of the application review process. If you require specific scopes please make sure to mention. By default access to the users public information and email address is provided.

Scope Description
actions Allow actions such as like, comment and follow on the users behalf.
projects Allow access to the users projects for updating and deleting.
credits Allow access to the users credits for create, accept, decline or delete.
lists Allow access to the users lists (public and private) for create, update and delete.
messages Allow access to the users messages to send and delete messages.
settings Allow access to update the users settings, including the avatar and cover images.
upload Upload projects on the users behalf

Request Authorization

Example Flow

https://api.twine.fm/oauth/authorize?client_id=foobar&redirect_uri=http://foo.example.com/twine&response_type=code&scope=actions,projects,credits,lists,messages,settings,upload

To start the OAuth process, construct the initiation URL which the user will visit in order to grant permission to your application. It describes the permissions your application requires scope, who the client application is client_id, and where the user should be redirected to after they grant or deny permissions to your application redirect_uri.

When Requesting Authorization, the redirect_uri should match the Callback URL you set in your Twine settings.

HTTP Request

GET https://api.twine.fm/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope={scopes}

URL Parameters

Parameter Required Description Default
client_id
string
Yes Application key
redirect_uri
url
Yes URL where the user will be redirected to afterwards. The value of this parameter must match one entered when creating the application.
response_type
string
Yes This must always be set to code
scope
string
No Permissions you are requesting. See above for list of available scopes. Scopes are delimited by a comma (“,”)

Finish Authorization

Example Request

curl "https://api.twine.fm/oauth/access_token"
  -X POST
  -d grant_type="authorization_code"
  -d client_id="foobar"
  -d client_secret="barbaz"
  -d redirect_uri="http://foo.example.com/twine"
  -d code="random_code"

Example Response

{
  "access_token": "access_token",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "refresh_token"
}

Once the user returns to your application via the redirect_uri you specified, there will be a code query string parameter appended to that URL. Exchange the authorization code for an access_token and refresh_token pair.

HTTP Request

POST https://api.twine.fm/oauth/access_token

Request Parameters

Parameter Required Description Default
client_id
string
Yes Application key
client_secret
string
Yes Application secret
grant_type
string
Yes This must be set to authorization_code
redirect_uri
url
Yes URL where the user will be redirected to afterwards. The value of this parameter must match one entered when creating the application.
code
string
Yes The authorization code included in the redirect URL

Refresh Token

Example Request

curl "https://api.twine.fm/oauth/access_token"
  -X POST
  -d grant_type="refresh_token"
  -d client_id="foobar"
  -d client_secret="barbaz"
  -d refresh_token="refresh_token"

Example Response

{
  "access_token": "new_access_token",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "new_refresh_token"
}

Use a valid refresh_token to generate a new access_token and refresh_token pair.

NOTE: The refresh_token you receive will change every time you exchange the refresh_token for a new token pair. Only the most recently issued refresh_token will allow you to receive a new pair.

HTTP Request

POST https://api.twine.fm/oauth/access_token

Request Parameters

Parameter Required Description Default
client_id
string
Yes Application key
client_secret
string
Yes Application secret
refresh_token
string
Yes A valid refresh token
grant_type
string
Yes This must be set to refresh_token
scope
string
No Permissions you are requesting. See above for list of available scopes. Scopes are delimited by a comma (“,”)

Client Credentials

Example Request for Client Credentials

curl "https://api.twine.fm/oauth/access_token"
  -X POST
  -d grant_type="client_credentials"
  -d client_id="foobar"
  -d client_secret="barbaz"

Example Response

{
  "access_token": "access_token",
  "token_type": "Bearer",
  "expires_in": 7200
}

Applications can use the client credentials grant to get an access token that will provide access the the account associated with that client.

HTTP Request

POST https://api.twine.fm/oauth/access_token

Request Parameters

Parameter Required Description Default
client_id
string
Yes Application key
client_secret
string
Yes Application secret
grant_type
string
Yes This must be set to client_credentials
scope
string
No Permissions you are requesting. See above for list of available scopes. Scopes are delimited by a comma (“,”)

Responses

Success

All Paginated responses also contain a meta block. Example:

{
  "resource": [
    {
      ...
    }
  ],
  "meta": {
    "pagination": {
      "total": 100,
      "count": 10,
      "per_page": 10,
      "current_page": 2,
      "next_page": 3,
      "total_pages": 10,
      "links": {
        "previous": "https://www.twine.fm/...?page=1",
        "next": "https://www.twine.fm/...?page=3"
      }
    }
  }
}

The Twine API uses the following codes for successful requests:

Code Meaning
200 Successful request
201 Resource created
204 Resource delete

Errors

The Twine API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – You are not authorized for the resource requested, or you are not allowed to perform that action
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
406 Not Acceptable – You requested a format that isn’t json
422 Unprocessable Entity – Your request sucks
429 Too Many Requests – Your request rate is to high! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Users

To interact with a user for either getting or updating a users information.

All user endpoints can have an optional include query parameter. This can be used to get additional information about the user, such as the avatar and cover urls.

Parameter Required Description Default
include
string
No Include additional information about the user.
Available includes: social, avatars, covers

social: Provides additional information about if the user is connected to a social service or not.
avatars: Provides the urls to a users avatar in various sizes.
covers: Provides the urls to a users cover image in various sizes.

Get a user

Example Request:

curl "https://api.twine.fm/users/1"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "id": 1,
  "username": "foo",
  "displayname": "bar",
  "bio": "",
  "verified": true,
  "location": "baz",
  "available": false,
  "pro": false,
  "featured_roles": [],
  "joined": "2015-12-01T00:00:00+0000",
  "last_active": "2015-12-01T00:00:00+0000",
  "links": {
    "main": "https://www.twine.fm/...",
    "short": "http://clw.ee/..."
  },
  "email": "foo@bar.com",
  "dob": "2015-12-01T00:00:00+0000"
}

Get information about a user. If the authenticated user is also the user being requested then the users additional personal information is made available such as email and dob.

HTTP Request

GET https://api.twine.fm/me
GET https://api.twine.fm/users/{user_id}

URL Parameters

Parameter Required Description Default
user_id
string or integer
Yes The username or id of the user

Update a user

Example Request:

curl "https://api.twine.fm/users/1"
  -X PATCH
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d displayname="My Display Name"

Example Response:

{
  "id": 1,
  "username": "foo",
  "displayname": "My Display Name",
  "bio": "",
  "verified": true,
  "location": "baz",
  "available": false,
  "pro": false,
  "featured_roles": [],
  "joined": "2015-12-01T00:00:00+0000",
  "last_active": "2015-12-01T00:00:00+0000",
  "links": {
    "main": "https://www.twine.fm/...",
    "short": "http://clw.ee/..."
  },
  "email": "foo@bar.com",
  "dob": "2015-12-01T00:00:00+0000"
}

Update a users information including their avatars and covers.

Scopes

settings

HTTP Request

PATCH https://api.twine.fm/users/{user_id}

URL Parameters

Parameter Required Description Default
user_id
string or integer
Yes The username or id of the user

Request Parameters

Parameter Required Description Default
displayname
string
No New display name
avatar
image or url
No New Avatar.
Required with crop[avatar]
crop[avatar][h]
integer
No Crop the avatar, set the crop height.
Required with crop[avatar][w], crop[avatar][x], crop[avatar][y]
crop[avatar][w]
integer
No Crop the avatar, set the crop width.
Required with crop[avatar][h], crop[avatar][x], crop[avatar][y]
crop[avatar][x]
integer
No Crop the avatar, set the crop x axis.
Required with crop[avatar][h], crop[avatar][w], crop[avatar][y]
crop[avatar][y]
integer
No Crop the avatar, set the crop y axis.
Required with crop[avatar][h], crop[avatar][w], crop[avatar][x]
cover
image or url
No New Cover.
Required with crop[cover]
crop[cover][h]
integer
No Crop the cover, set the crop height.
Required with crop[cover][w], crop[cover][x], crop[cover][y]
crop[cover][w]
integer
No Crop the cover, set the crop width.
Required with crop[cover][h], crop[cover][x], crop[cover][y]
crop[cover][x]
integer
No Crop the cover, set the crop x axis.
Required with crop[cover][h], crop[cover][w], crop[cover][y]
crop[cover][y]
integer
No Crop the cover, set the crop y axis.
Required with crop[cover][h], crop[cover][w], crop[cover][x]
bio
string
No New Bio.
Max of 3000 characters
website
url
No New Website
location
string
No New Location string
dob
date
No Date of birth in format: yyyy-mm-dd
available
boolean
No Set if available for hire.
Requires a pro subscription
featured_roles
array
No Set an array of featured roles.
Max 3, must be in suggested roles list

Get followers

Example Request:

curl "https://api.twine.fm/users/1/followers"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "followers": [
    {
      "timestamp": "2015-12-01T00:00:00+0000",
      "user": {
        "id": 2,
        "username": "foo2",
        "displayname": "foo bar",
        "bio": "",
        "verified": true,
        "location": "",
        "available": false,
        "pro": false,
        "featured_roles": [],
        "joined": "2015-12-01T00:00:00+0000",
        "last_active": "2015-12-01T00:00:00+0000",
        "links": {
          "main": "https://www.twine.fm/...",
          "short": "http://clw.ee/..."
        }
      }
    }
  ]
}

Get followers. Results are paginated

HTTP Request

GET https://api.twine.fm/users/{user_id}/followers

URL Parameters

Parameter Required Description Default
user_id
string or integer
Yes The username or id of the user
page
integer
No Page 1
limit
integer
No Limit the number of results
Max: 100
10

Get following

Example Request:

curl "https://api.twine.fm/users/1/following"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "followings": [
    {
      "timestamp": "2015-12-01T00:00:00+0000",
      "user": {
        "id": 2,
        "username": "foo2",
        "displayname": "foo bar",
        "bio": "",
        "verified": true,
        "location": "",
        "available": false,
        "pro": false,
        "featured_roles": [],
        "joined": "2015-12-01T00:00:00+0000",
        "last_active": "2015-12-01T00:00:00+0000",
        "links": {
          "main": "https://www.twine.fm/...",
          "short": "http://clw.ee/..."
        }
      }
    }
  ]
}

Get following. Results are paginated

HTTP Request

GET https://api.twine.fm/users/{user_id}/following

URL Parameters

Parameter Required Description Default
user_id
string or integer
Yes The username or id of the user
page
integer
No Page 1
limit
integer
No Limit the number of results
Max: 100
10

Follow a user

Example Request:

curl "https://api.twine.fm/users/2/follow"
  -X PUT
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "following": true
}

Follow a user. The same response is given if you are already following that user.

Scopes

actions

HTTP Request

PUT https://api.twine.fm/users/{user_id}/follow

URL Parameters

Parameter Required Description Default
user_id
string or integer
Yes The username or id of the user to follow

Unfollow a user

Example Request:

curl "https://api.twine.fm/users/1/follow"
  -X DELETE
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "following": false
}

Unfollow a user. The same response is given if you are already not following that user.

Scopes

actions

HTTP Request

DELETE https://api.twine.fm/users/{user_id}/follow

URL Parameters

Parameter Required Description Default
user_id
string or integer
Yes The username or id of the user to unfollow

Check if following user

Example Request:

curl "https://api.twine.fm/users/1/follow"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "following": true
}

Check if following user

Scopes

actions

HTTP Request

Get https://api.twine.fm/users/{user_id}/follow

URL Parameters

Parameter Required Description Default
user_id
string or integer
Yes The username or id of the user to check

Get a users projects

Example Request:

curl "https://api.twine.fm/users/1/projects"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "projects": [
    {
      "id": 1,
      "title": "foo",
      "description": "bar",
      "tags": [
          "baz",
      ],
      "mediaType": "video",
      "created": "2015-12-01T00:00:00+0000",
      "last_updated": "2015-12-01T00:00:00+0000",
      "size": 73284,
      "active": false,
      "solo": false,
      "links": {
          "main": "https://www.twine.fm/...",
          "short": "http://clw.ee/cl..."
      }
    }
  ]
}

Get a users projects. If getting the authenticated users projects then the inactive projects are included in the response.

HTTP Request

GET https://api.twine.fm/users/{user_id}/projects

URL Parameters

Parameter Required Description Default
user_id
string or integer
Yes The username or id of the user
page
integer
No Page 1
limit
integer
No Limit the number of results
Max: 100
10

Example Request:

curl "https://api.twine.fm/users/1/projects/featured"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "projects": [
    {
      "id": 1,
      "title": "foo",
      "description": "bar",
      "tags": [
          "baz",
      ],
      "mediaType": "video",
      "created": "2015-12-01T00:00:00+0000",
      "last_updated": "2015-12-01T00:00:00+0000",
      "size": 73284,
      "active": false,
      "solo": false,
      "links": {
          "main": "https://www.twine.fm/...",
          "short": "http://clw.ee/cl..."
      }
    }
  ]
}

Get a users featured projects. If no featured project has been set by the user, the latest project will be returned. Currently the user can only have one featured project.

HTTP Request

GET https://api.twine.fm/users/{user_id}/projects/featured

URL Parameters

Parameter Required Description Default
user_id
string or integer
Yes The username or id of the user

Get a users lists

Example Request:

curl "https://api.twine.fm/users/1/lists"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "lists": [
    {
      "id": 1,
      "name": "foo",
      "public": true,
      "timestamp": "2015-12-01T00:00:00+0000"
    }
  ]
}

Get a users lists. If getting the authenticated users lists then the private lists are included in the response.

HTTP Request

GET https://api.twine.fm/users/{user_id}/lists

URL Parameters

Parameter Required Description Default
user_id
string or integer
Yes The username or id of the user
page
integer
No Page 1
limit
integer
No Limit the number of results
Max: 100
10

Get a users credits

Example Request:

curl "https://api.twine.fm/users/1/credits"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "credits": [
    {
      "id": 1,
      "pending": false,
      "active": true,
      "timestamp": "2015-12-01T00:00:00+0000",
      "roles": [
        {
          "id": 1,
          "name": "Audio Mixer",
          "pending": false,
          "active": true,
          "timestamp": "2015-12-01T00:00:00+0000"
        },
        {
          "id": 2,
          "name": "Sound Editor",
          "pending": false,
          "active": true,
          "timestamp": "2015-12-01T00:00:00+0000"
        }
      ]
    }
  ]
}

Example Request:

curl "https://api.twine.fm/users/1/credits?include=roles:limit(1):page(2)"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "credits": [
    {
      "id": 1,
      "pending": false,
      "active": true,
      "timestamp": "2015-12-01T00:00:00+0000",
      "roles": [
        {
          "id": 2,
          "name": "Sound Editor",
          "pending": false,
          "active": true,
          "timestamp": "2015-12-01T00:00:00+0000"
        }
      ]
    }
  ]
}

Get a users credits. If getting the authenticated users credits then the pending/inactive credits are included in the response. Results are paginated. Roles are also paginated, by default only the first 10 are returned.

HTTP Request

GET https://api.twine.fm/users/{user_id}/credits

URL Parameters

Parameter Required Description Default
user_id
string or integer
Yes The username or id of the user
page
integer
No Page 1
limit
integer
No Limit the number of results
Max: 100
10

Get a users collaboration notices

Example Request:

curl "https://api.twine.fm/users/1/notices/collaboration"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "collaborations": [
    {
      "id": 2,
      "text": "Looking for a DJ for an amazing project I have lined up",
      "roles": [
        "DJ"
      ],
      "timestamp": "2015-12-01T00:00:00+0000",
      "expires_at": "2015-12-07T00:00:00+0000",
      "active": true,
      "amount": 3000,
      "currency": "gbp",
      "links": {
        "main": "https://www.twine.fm/collaborate/b6c6g1",
        "short": "http://clw.ee/b6c6g1"
      }
    },
    {
      "id": 1,
      "text": "Looking for a DJ for an amazing project I have lined up",
      "roles": [
        "DJ"
      ],
      "timestamp": "2015-12-01T00:00:00+0000",
      "expires_at": "2015-12-07T00:00:00+0000",
      "active": false,
      "amount": 1000,
      "currency": "gbp",
      "links": {
        "main": "https://www.twine.fm/collaborate/b6c6g0",
        "short": "http://clw.ee/b6c6g0"
      }
    }
  ]
}

Get a users collaboration notices. If getting the authenticated users notices then the inactive notices are included in the response. Results are paginated.

HTTP Request

GET https://api.twine.fm/users/{user_id}/notices/collaboration

URL Parameters

Parameter Required Description Default
user_id
string or integer
Yes The username or id of the user
page
integer
No Page 1
limit
integer
No Limit the number of results
Max: 100
10

Projects

To interact with a users project for either creating or updating a project.

All project endpoints can have an optional include query parameter. This can be used to get additional information about the project, such as the users preferences, its stats, its user information and the thumbnail urls.

Parameter Required Description Default
include
string
No Include additional information about the project.
Available includes: user, stats, thumbnails, preferences, licenses

user: Provides the user that uploaded the project.
stats: Provides the stats about a project. The number of likes, comments, etc.
thumbnails: Provides the urls to a projects thumbnails in various sizes.
preferences: Provides the projects preferences, if its downloadable or commentable.
licenses: Provides the projects licenses as set by the user.

Get a project

Example Request:

curl "https://api.twine.fm/projects/1?include=preferences,stats"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "id": 1,
  "title": "foo",
  "description": "bar",
  "tags": [
    "baz",
  ],
  "mediaType": "video",
  "created": "2015-12-01T00:00:00+0000",
  "last_updated": "2015-12-01T00:00:00+0000",
  "size": 73284,
  "active": false,
  "solo": false,
  "links": {
    "main": "https://www.twine.fm/...",
    "short": "http://clw.ee/cl..."
  },
  "stats": {
    "downloads": 0,
    "views": 0,
    "plays": 0,
    "likes": 0,
    "comments": 0
  },
  "preferences": {
    "downloadable": true,
    "commentable": true
  }
}

Get information about a project.

HTTP Request

GET https://api.twine.fm/projects/{project_id}

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project

Upload a project

Example Request:

curl "https://api.twine.fm/projects"
  -X POST
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d title="My first video"
  -d file=@/path/to/video.mp4

Example Response:

{
  "id": 2,
  "title": "My first video",
  "description": "",
  "tags": [],
  "mediaType": null,
  "created": "2015-12-01T00:00:00+0000",
  "last_updated": "2015-12-01T00:00:00+0000",
  "size": 123123,
  "active": false,
  "solo": false,
  "links": {
    "main": "https://www.twine.fm/...",
    "short": "http://clw.ee/cl..."
  }
}

Upload a file and create a new project.

Scopes

projects and uploads

HTTP Request

POST https://api.twine.fm/projects

Request Parameters

Parameter Required Description Default
title
string
Yes The title of the project.
Must be between 1 and 100 characters.
file
file or url
Yes The file being uploaded.
Must be a valid file.
description
string
No The project description.
Must be between 1 and 3000 characters.
thumbnail
image or url
No The thumbnail for the project. One will be generated from the project file if not provided. If the project file is an image this will be ignored.
Must be a valid image file. Required with crop[thumbnail]
crop[thumbnail][h]
integer
No Crop the thumbnail, set the crop height.
Required with crop[thumbnail][w], crop[thumbnail][x], crop[thumbnail][y]
crop[thumbnail][w]
integer
No Crop the thumbnail, set the crop width.
Required with crop[thumbnail][h], crop[thumbnail][x], crop[thumbnail][y]
crop[thumbnail][x]
integer
No Crop the thumbnail, set the crop x axis.
Required with crop[thumbnail][h], crop[thumbnail][w], crop[thumbnail][y]
crop[thumbnail][y]
integer
No Crop the thumbnail, set the crop y axis.
Required with crop[thumbnail][h], crop[thumbnail][w], crop[thumbnail][x]
solo
boolean
No Let Twine know that no one else collaborated with you on this file. false
downloadable
boolean
No Enable or disable downloads for the project. true
commentable
boolean
No Enable or disable comments for the project.
Requires a pro subscription
true
widget[branding]
boolean
No Enable or disable widget branding for the project.
Requires a pro subscription
true
widget[embed]
boolean
No Enable or disable widget embed for the project.
Requires a pro subscription
true
widget[color]
string
No Set the color of the widget for the project. Possible values = red, green, purple or default.
Requires a pro subscription
default
licenses
integer
No Set the license for the project.

Update an existing project

Example Request:

curl "https://api.twine.fm/projects/2"
  -X PATCH
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d title="My awesome video"
  -d thumbnail=@/path/to/image.jpg
  -d description="This is my awesome video!!! #video #awesome"
  -d solo=true

Example Response:

{
  "id": 2,
  "title": "My awesome video",
  "description": "This is my awesome video!!!",
  "tags": [
    "video",
    "awesome"
  ],
  "mediaType": "video",
  "created": "2015-12-01T00:00:00+0000",
  "last_updated": "2015-12-01T00:00:00+0000",
  "size": 123123,
  "active": true,
  "solo": true,
  "links": {
    "main": "https://www.twine.fm/...",
    "short": "http://clw.ee/cl..."
  }
}

Update an existing projects information.

Scopes

projects

HTTP Request

PATCH https://api.twine.fm/projects/{project_id}

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project

Request Parameters

Parameter Required Description Default
title
string
No The title of the project.
Must be between 1 and 100 characters.
description
string
No The project description.
Must be between 1 and 3000 characters.
thumbnail
image or url
No The thumbnail for the project. One will be generated from the project file if not provided. If the project file is an image this will be ignored.
Must be a valid image file. Required with crop[thumbnail]
crop[thumbnail][h]
integer
No Crop the thumbnail, set the crop height.
Required with crop[thumbnail][w], crop[thumbnail][x], crop[thumbnail][y]
crop[thumbnail][w]
integer
No Crop the thumbnail, set the crop width.
Required with crop[thumbnail][h], crop[thumbnail][x], crop[thumbnail][y]
crop[thumbnail][x]
integer
No Crop the thumbnail, set the crop x axis.
Required with crop[thumbnail][h], crop[thumbnail][w], crop[thumbnail][y]
crop[thumbnail][y]
integer
No Crop the thumbnail, set the crop y axis.
Required with crop[thumbnail][h], crop[thumbnail][w], crop[thumbnail][x]
solo
boolean
No Let Twine know that no one else collaborated with you on this file.
downloadable
boolean
No Enable or disable downloads for the project.
commentable
boolean
No Enable or disable comments for the project.
Requires a pro subscription
widget[branding]
boolean
No Enable or disable widget branding for the project.
Requires a pro subscription
widget[embed]
boolean
No Enable or disable widget embed for the project.
Requires a pro subscription
widget[color]
string
No Set the color of the widget for the project. Possible values = red, green, purple or default.
Requires a pro subscription
licenses
integer
No Set the license for the project.

Delete an existing project

Example Request:

curl "https://api.twine.fm/projects/2"
  -X DELETE
  -H "Authorization: Bearer ACCESS_TOKEN"

Delete an existing project. This is a soft delete and the project can still be restored within 7 Days. After 7 days it will be permanently deleted and can not be restored.

Scopes

projects

HTTP Request

DELETE https://api.twine.fm/projects/{project_id}

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project

Restore a deleted project

Example Request:

curl "https://api.twine.fm/projects/2"
  -X PUT
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "id": 2,
  "title": "My awesome video",
  "description": "This is my awesome video!!!",
  "tags": [
    "video",
    "awesome"
  ],
  "mediaType": "video",
  "created": "2015-12-01T00:00:00+0000",
  "last_updated": "2015-12-01T00:00:00+0000",
  "size": 123123,
  "active": true,
  "solo": true,
  "links": {
    "main": "https://www.twine.fm/...",
    "short": "http://clw.ee/cl..."
  }
}

Restore a deleted project. Trying to restore a project that does not exist or have been deleted after the 7 days limit will result in a 404 response.

Scopes

projects

HTTP Request

PUT https://api.twine.fm/projects/{project_id}

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project

Download a downloadable project.

Example Request:

curl "https://api.twine.fm/projects/2/download"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Download a downloadable project. Trying to download a non-existent or non-downloadable project will result in a 404 error code.

HTTP Request

GET https://api.twine.fm/projects/{project_id}/download

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project

Get all public lists a project is in

Example Request:

curl "https://api.twine.fm/projects/2/lists"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "lists": [
    {
      "id": 1,
      "name": "foo",
      "public": true,
      "timestamp": "2015-12-01T00:00:00+0000",
      "num_of_items": 3
    }
  ]
}

Get all the public lists that this project is in. Results are paginated

HTTP Request

GET https://api.twine.fm/projects/{project_id}/lists

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project
page
integer
No Page 1
limit
integer
No Limit the number of results
Max: 100
10

Get all credits for a project

Example Request:

curl "https://api.twine.fm/projects/2/credits"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Responses:

{
  "credits": [
    {
      "id": 1,
      "pending": false,
      "active": true,
      "timestamp": "2015-12-01T00:00:00+0000",
      "roles": [
        {
          "id": 1,
          "name": "Accountant",
          "pending": false,
          "active": true,
          "timestamp": "2015-12-01T00:00:00+0000"
        }
      ]
    }
  ]
}

Get all credits for a project. Results are paginated

HTTP Request

GET https://api.twine.fm/projects/{project_id}/credits

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project
page
integer
No Page 1
limit
integer
No Limit the number of results
Max: 100
10

Example Request:

curl "https://api.twine.fm/projects/2/related"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "relateds": [
    {
      "score": 0.5120234,
      "related": {
        "id": 2,
        "title": "bar",
        "description": "",
        "tags": [],
        "mediaType": "video",
        "created": "2015-12-01T00:00:00+0000",
        "last_updated": "2015-12-01T00:00:00+0000",
        "size": 69309933,
        "active": true,
        "solo": false,
        "links": {
          "main": "https://www.twine.fm/...",
          "short": "http://clw.ee/..."
        }
      }
    }
  ]
}

Get all the related projects for a given project. Results are paginated

HTTP Request

GET https://api.twine.fm/projects/{project_id}/related

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project
page
integer
No Page 1
limit
integer
No Limit the number of results
Max: 100
10

Like a project

Example Request:

curl "https://api.twine.fm/projects/2/like"
  -X PUT
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "like": true
}

Like a project

Scopes

projects and actions

HTTP Request

PUT https://api.twine.fm/projects/{project_id}/like

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project

Unlike a project

Example Request:

curl "https://api.twine.fm/projects/2/like"
  -X DELETE
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "like": false
}

Unlike a project.

Scopes

projects and actions

HTTP Request

DELETE https://api.twine.fm/projects/{project_id}/like

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project

Check if project liked

Example Request:

curl "https://api.twine.fm/projects/2/like"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "like": true
}

Check if project liked.

Scopes

projects and actions

HTTP Request

GET https://api.twine.fm/projects/{project_id}/like

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project

Comments

To interact with a projects comments for either creating, removing, liking a comment.

All comment endpoints can have an optional include query parameter. This can be used to get additional information about the comment, such as the user, the project and the replies

Parameter Required Description Default
include
string
No Include additional information about the comment.
Available includes: user, project, replies.
A max of 10 replies can be returned using the includes, if you need more use the replies endpoint.

user: Provides the user that created the comment.
project: Provides the project the comment was created on.
replies: Provides the replies made to the comment.

Get all comments for a project

Example Request:

curl "https://api.twine.fm/projects/2/comments"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "comments": [
    {
      "id": 1,
      "text": "foo",
      "timestamp": "2015-12-01T00:00:00+0000",
      "likes": 0,
      "no_of_replies": 0
    }
  ]
}

Get all comments for a project

HTTP Request

GET https://api.twine.fm/projects/{project_id}/comments

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project
page
integer
No Page 1
limit
integer
No Limit the number of comments
Max: 100
10

Get a comment

Example Request:

curl "https://api.twine.fm/projects/2/comments/1"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "id": 1,
  "text": "foo",
  "timestamp": "2015-12-01T00:00:00+0000",
  "likes": 0,
  "no_of_replies": 0
}

Example Request:

curl "https://api.twine.fm/projects/2/comments/1?include=replies"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "id": 1,
  "text": "foo",
  "timestamp": "2015-12-01T00:00:00+0000",
  "likes": 0,
  "no_of_replies": 0,
  "replies": []
}

Get a comment

HTTP Request

GET https://api.twine.fm/projects/{project_id}/comments/{comment_id}

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project
comment_id
string
Yes The id of the Comment

Post a comment

Example Request:

curl "https://api.twine.fm/projects/2/comments"
  -X POST
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d text="bar"

Example Response:

{
  "id": 2,
  "text": "bar",
  "timestamp": "2015-12-01T00:00:00+0000",
  "likes": 0,
  "no_of_replies": 0
}

Post a comment

Scopes

actions

HTTP Request

POST https://api.twine.fm/projects/{project_id}/comments

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project

Request Parameters

Parameter Required Description Default
text
string
Yes The comment text.
Must be between 1 and 1000 characters.

Get all comment replies

Example Request:

curl "https://api.twine.fm/projects/2/comments/1/replies"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response

{
  "comments": [
    {
      "id": 3,
      "text": "foobar",
      "timestamp": "2015-12-01T00:00:00+0000",
      "likes": 0,
      "parent_id": 1
    }
  ]
}

Get all comment replies. Results are paginated

HTTP Request

GET https://api.twine.fm/projects/{project_id}/comments/{comment_id}/replies

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project
comment_id
string
Yes The id of the Comment
page
integer
No Page 1
limit
integer
No Limit the number of comments
Max: 100
10

Post a reply to a comment

Example Request:

curl "https://api.twine.fm/projects/2/comments/1/replies"
  -X POST
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d text="foo2"

Example Response

{
  "id": 4,
  "text": "foo2",
  "timestamp": "2015-12-01T00:00:00+0000",
  "likes": 0,
  "parent_id": 1
}

Post a reply to a comment

Scopes

actions

HTTP Request

POST https://api.twine.fm/projects/{project_id}/comments/{comment_id}/replies

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project
comment_id
string
Yes The id of the Comment

Request Parameters

Parameter Required Description Default
text
string
Yes The comment text.
Must be between 1 and 1000 characters.

Delete a comment or reply

Example Request:

curl "https://api.twine.fm/projects/2/comments/1"
  -X DELETE
  -H "Authorization: Bearer ACCESS_TOKEN"

Delete a comment or reply

Scopes

actions

HTTP Request

DELETE https://api.twine.fm/projects/{project_id}/comments/{comment_id}

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project
comment_id
string
Yes The id of the comment or reply

Like a comment or reply

Example Request:

curl "https://api.twine.fm/projects/2/comments/2/like"
  -X PUT
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "like": true
}

Like a comment or a comment reply.

Scopes

actions

HTTP Request

PUT https://api.twine.fm/projects/{project_id}/comments/{comment_id}/like

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project
comment_id
string
Yes The id of the comment or reply

Unlike a comment or reply

Example Request:

curl "https://api.twine.fm/projects/2/comments/2/like"
  -X DELETE
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "like": false
}

Unlike a comment or a comment reply

Scopes

actions

HTTP Request

DELETE https://api.twine.fm/projects/{project_id}/comments/{comment_id}/like

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project
comment_id
string
Yes The id of the comment or reply

Check if liked a comment or reply

Example Request:

curl "https://api.twine.fm/projects/2/comments/2/like"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "like": true
}

Check if liked a comment or reply

Scopes

actions

HTTP Request

GET https://api.twine.fm/projects/{project_id}/comments/{comment_id}/like

URL Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project
comment_id
string
Yes The id of the comment or reply

Credits

To interact with a projects credits for either creating or removing a credit.

All credit endpoints except GET /suggestedRoles can have an optional include query parameter. This can be used to get additional information about the credit, such as the user or the project

Parameter Required Description Default
include
string
No Include additional information about the credit.
Available includes: user, project, roles.
A max of 10 roles can be returned using the includes, if you need more use the roles endpoint.

user: Provides the user associated with the credit.
project: Provides the project associated with the credit.
roles: Provides the credit roles.

By default, credit requests include the first 10 roles as the roles are paginated. To get more you can use ?include=roles:limit(10):page(2) to iterate through the pages of roles.

Get all suggested roles

Example Request:

curl "https://api.twine.fm/suggestedRoles"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "suggested_roles": [
    {
      "id": 1,
      "name": "foo"
    },
    {
      "id": 2,
      "name": "bar"
    }
  ]
}

Get all suggested roles. Results are paginated

HTTP Request

GET https://api.twine.fm/suggestedRoles

URL Parameters

Parameter Required Description Default
page
integer
No Page 1
limit
integer
No Limit the number of comments
Max: 100
10

Get a credit

Example Request:

curl "https://api.twine.fm/credits/1"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Responses:

{
  "id": 1,
  "pending": false,
  "active": true,
  "timestamp": "2015-12-01T00:00:00+0000",
  "roles": [
    {
      "id": 1,
      "name": "Accountant",
      "pending": false,
      "active": true,
      "timestamp": "2015-12-01T00:00:00+0000"
    }
  ]
}

Get a credit

HTTP Request

GET https://api.twine.fm/credits/{credit_id}

URL Parameters

Parameter Required Description Default
credit_id
integer
Yes The id of the Credit

Credit a user on a project

Example Request:

curl "https://api.twine.fm/credits"
  -X POST
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d project_id=1
  -d users[]=2
  -d users[]=3
  -d roles[]=Actor
  -d roles[]=Accountant

Example Response:

{
  "credits": [
    {
      "id": 2,
      "pending": false,
      "active": true,
      "timestamp": "2015-12-01T00:00:00+0000",
      "roles": [
        {
          "id": 74,
          "name": "Accountant",
          "pending": true,
          "active": false,
          "timestamp": "2015-12-01T00:00:00+0000"
        },
        {
          "id": 75,
          "name": "Actor",
          "pending": true,
          "active": false,
          "timestamp": "2015-12-01T00:00:00+0000"
        }
      ]
    },
    {
      "id": 3,
      "pending": false,
      "active": true,
      "timestamp": "2015-12-01T00:00:00+0000",
      "roles": [
        {
          "id": 76,
          "name": "Accountant",
          "pending": true,
          "active": false,
          "timestamp": "2015-12-01T00:00:00+0000"
        },
        {
          "id": 77,
          "name": "Actor",
          "pending": true,
          "active": false,
          "timestamp": "2015-12-01T00:00:00+0000"
        }
      ]
    }
  ]
}

Example Request:

curl "https://api.twine.fm/credits"
  -X POST
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d project_id=1
  -d users[0][type]=email
  -d users[0][data]=foo@bar.com
  -d roles[]=Accountant

Example Response:

{
  "credits": [
    {
      "id": 4,
      "pending": false,
      "active": true,
      "timestamp": "2015-12-01T00:00:00+0000",
      "roles": [
        {
          "id": 78,
          "name": "Accountant",
          "pending": true,
          "active": false,
          "timestamp": "2015-12-01T00:00:00+0000"
        }
      ]
    }
  ]
}

Example Request:

curl "https://api.twine.fm/credits"
  -X POST
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d project_id=1
  -d users[0][type]=twitter
  -d users[0][data]=123123
  -d users[0][meta][username]=test
  -d users[0][meta][displayname]=Test
  -d users[0][meta][avatar]=http://twitter.com/avatar
  -d roles[]=Accountant

Example Response:

{
  "credits": [
    {
      "id": 5,
      "pending": false,
      "active": true,
      "timestamp": "2015-12-01T00:00:00+0000",
      "roles": [
        {
          "id": 79,
          "name": "Accountant",
          "pending": true,
          "active": false,
          "timestamp": "2015-12-01T00:00:00+0000"
        }
      ]
    }
  ]
}

Credit a user on a project. Results are paginated

Scopes

credits

HTTP Request

POST https://api.twine.fm/credits

Request Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project
users
array
Yes An array of user ids or an array with keys type, data and meta in case of a third party credit or an email credit where type is in [email, facebook, twitter, google, soundcloud, vimeo]. If type is email then data should be an email address and meta should be empty. If type is not email, then data should be the id of the social platform used in type and meta should contain the username, displayname and an optional avatar property (which must be a url).
roles
array
Yes An array of roles to credit the given users with.
Must be one of the suggested roles which can be found using the GET /suggestedRoles endpoint.

Delete a credit

Example Request:

curl "https://api.twine.fm/credits/1"
  -X DELETE
  -H "Authorization: Bearer ACCESS_TOKEN"

Delete a credit and all its roles

Scopes

credits

HTTP Request

DELETE https://api.twine.fm/credits/{credit_id}

URL Parameters

Parameter Required Description Default
credit_id
integer
Yes The id of the Credit

Get all roles for credit

Example Request:

curl "https://api.twine.fm/credits/2/roles"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "roles": [
    {
      "id": 74,
      "name": "Accountant",
      "pending": false,
      "active": true,
      "timestamp": "2015-12-01T00:00:00+0000"
    },
    {
      "id": 75,
      "name": "Actor",
      "pending": false,
      "active": true,
      "timestamp": "2015-12-01T00:00:00+0000"
    }
  ]
}

Get all roles for credit. Results are paginated

HTTP Request

GET https://api.twine.fm/credits/{credit_id}/roles

URL Parameters

Parameter Required Description Default
credit_id
integer
Yes The id of the Credit
page
integer
No Page 1
limit
integer
No Limit the number of results
Max: 100
10

Delete a role on a credit

Example Request:

curl "https://api.twine.fm/credits/1/roles/1"
  -X DELETE
  -H "Authorization: Bearer ACCESS_TOKEN"

Delete a role on a credit

Scopes

credits

HTTP Request

DELETE https://api.twine.fm/credits/{credit_id}/roles/{role_id}

URL Parameters

Parameter Required Description Default
credit_id
integer
Yes The id of the Credit
role_id
string
Yes The id of the Role

Accept a roles on a credit

Example Request:

curl "https://api.twine.fm/credits/1/roles/1/accept"
  -X PUT
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "id": 1,
  "pending": false,
  "active": true,
  "timestamp": "2015-12-01T00:00:00+0000",
  "roles": [
    {
      "id": 1,
      "name": "Accountant",
      "pending": false,
      "active": true,
      "timestamp": "2015-12-01T00:00:00+0000"
    }
  ]
}

Accept a roles on a credit. The same request has to be made by both the project owner and the creditee for the role to be active (not pending). If the project owner is who credited with the role, then only the creditee has to accept. If the creditee is who credited with the role then only the project owner has to accept. If the project owner is also the creditee, then the role is automatically accepted and made active.

Scopes

credits

HTTP Request

PUT https://api.twine.fm/credits/{credit_id}/roles/{role_id}/accept

URL Parameters

Parameter Required Description Default
credit_id
integer
Yes The id of the Credit
role_id
string
Yes The id of the Role

Decline a roles on a credit

Example Request:

curl "https://api.twine.fm/credits/1/roles/1/decline"
  -X PUT
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "id": 1,
  "pending": false,
  "active": true,
  "timestamp": "2015-12-01T00:00:00+0000",
  "roles": [
    {
      "id": 1,
      "name": "Accountant",
      "pending": false,
      "active": false,
      "timestamp": "2015-12-01T00:00:00+0000"
    }
  ]
}

Decline a roles on a credit.

Scopes

credits

HTTP Request

PUT https://api.twine.fm/credits/{credit_id}/roles/{role_id}/decline

URL Parameters

Parameter Required Description Default
credit_id
integer
Yes The id of the Credit
role_id
string
Yes The id of the Role

Lists

To interact with a users Lists for either getting, creating, updating or removing a list and list items.

All lists endpoints can have an optional include query parameter. This can be used to get additional information about the list, such as the user or the project

Parameter Required Description Default
include
string
No Include additional information about the list.
Available includes: user, items, thumbnails.

user: Provides the user that created the list.
items: Provides the items for the list.
thumbnails: Provides the urls to the lists thumbnails in various sizes.

Get a list

Example Request:

curl "https://api.twine.fm/lists/1"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "id": 1,
  "name": "foo",
  "public": false,
  "timestamp": "2015-12-01T00:00:00+0000",
  "num_of_items": 5
}

Get a list

HTTP Request

GET https://api.twine.fm/lists/{list_id}

URL Parameters

Parameter Required Description Default
list_id
string
Yes The id of the list

Create a list

Example Request:

curl "https://api.twine.fm/lists"
  -X POST
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d name="bar"

Example Response:

{
  "id": 2,
  "name": "bar",
  "public": true,
  "timestamp": "2015-12-01T00:00:00+0000",
  "num_of_items": 0
}

Create a list

Scopes

lists

HTTP Request

POST https://api.twine.fm/lists

Request Parameters

Parameter Required Description Default
name
string
Yes Name of the list.
Must be between 1 and 100 characters.

Update a list

Example Request:

curl "https://api.twine.fm/lists/1"
  -X PATCH
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d name="foobar"
  -d public=false

Example Response:

{  
  "id": 2,
  "name": "foobar",
  "public": false,
  "timestamp": "2015-12-01T00:00:00+0000",
  "num_of_items": 2
}

Update a list

Scopes

lists

HTTP Request

PATCH https://api.twine.fm/lists/{list_id}

URL Parameters

Parameter Required Description Default
list_id
string
Yes The id of the list

Request Parameters

Parameter Required Description Default
name
string
No Name of the list.
Must be between 1 and 100 characters.

Delete a list

Example Request:

curl "https://api.twine.fm/lists/1"
  -X DELETE
  -H "Authorization: Bearer ACCESS_TOKEN"

Delete a list

Scopes

lists

HTTP Request

DELETE https://api.twine.fm/lists/{list_id}

URL Parameters

Parameter Required Description Default
list_id
string
Yes The id of the list

Get all items in a list

Example Request:

curl "https://api.twine.fm/lists/1/items"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "items": [
    {
      "id": 1,
      "timestamp": "2015-12-01T00:00:00+0000",
      "project": {
        "id": 1,
        "title": "foo",
        "description": "",
        "tags": [],
        "mediaType": "audio",
        "created": "2015-12-01T00:00:00+0000",
        "last_updated": "2015-12-01T00:00:00+0000",
        "size": 3086964,
        "active": true,
        "solo": false,
        "links": {
          "main": "https://www.twine.fm/...",
          "short": "http://clw.ee/..."
        }
      }
    }
  ]
}

Get all items in a list. Results are paginated

HTTP Request

GET https://api.twine.fm/lists/{list_id}/items

URL Parameters

Parameter Required Description Default
list_id
string
Yes The id of the list
page
integer
No Page 1
limit
integer
No Limit the number of results
Max: 100
10

Get an item in a list

Example Request:

curl "https://api.twine.fm/lists/1/items/1"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "id": 1,
  "timestamp": "2015-12-01T00:00:00+0000",
  "project": {
    "id": 1,
    "title": "foo",
    "description": "",
    "tags": [],
    "mediaType": "audio",
    "created": "2015-12-01T00:00:00+0000",
    "last_updated": "2015-12-01T00:00:00+0000",
    "size": 3086964,
    "active": true,
    "solo": false,
    "links": {
      "main": "https://www.twine.fm/...",
      "short": "http://clw.ee/..."
    }
  }
}

Get an item in a list

HTTP Request

GET https://api.twine.fm/lists/{list_id}/items/{item_id}

URL Parameters

Parameter Required Description Default
list_id
string
Yes The id of the list
item_id
string
Yes The id of the item

Add a project to a list

Example Request:

curl "https://api.twine.fm/lists/1/items"
  -X POST
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d project_id=4

Example Response:

{
  "id": 2,
  "timestamp": "2015-12-01T00:00:00+0000",
  "project": {
    "id": 4,
    "title": "foobar4",
    "description": "",
    "tags": [],
    "mediaType": "video",
    "created": "2015-12-01T00:00:00+0000",
    "last_updated": "2015-12-01T00:00:00+0000",
    "size": 21103434,
    "active": true,
    "solo": false,
    "links": {
      "main": "https://www.twine.fm/...",
      "short": "http://clw.ee/..."
    }
  }
}

Add a project to a list

Scopes

lists

HTTP Request

POST https://api.twine.fm/lists/{list_id}/items

URL Parameters

Parameter Required Description Default
list_id
string
Yes The id of the list

Request Parameters

Parameter Required Description Default
project_id
string
Yes The id of the project to be added

Update a item in a list

Example Request:

curl "https://api.twine.fm/lists/1/items/1"
  -X PATCH
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d position=0

Example Response:

{
  "id": 2,
  "timestamp": "2015-12-01T00:00:00+0000",
  "project": {
    "id": 4,
    "title": "foobar4",
    "description": "",
    "tags": [],
    "mediaType": "video",
    "created": "2015-12-01T00:00:00+0000",
    "last_updated": "2015-12-01T00:00:00+0000",
    "size": 21103434,
    "active": true,
    "solo": false,
    "links": {
      "main": "https://www.twine.fm/...",
      "short": "http://clw.ee/..."
    }
  }
}

Update a item in a list

Scopes

lists

HTTP Request

PATCH https://api.twine.fm/lists/{list_id}/items/{item_id}

URL Parameters

Parameter Required Description Default
list_id
string
Yes The id of the list
item_id
string
Yes The id of the item

Request Parameters

Parameter Required Description Default
position
integer
Yes Position to move the item to in the list

Clear a list

Example Request:

curl "https://api.twine.fm/lists/1/items"
  -X DELETE
  -H "Authorization: Bearer ACCESS_TOKEN"

Clear a list

Scopes

lists

HTTP Request

DELETE https://api.twine.fm/lists/{list_id}/items

URL Parameters

Parameter Required Description Default
list_id
string
Yes The id of the list

Delete a item from a list

Example Request:

curl "https://api.twine.fm/lists/1/items/1"
  -X DELETE
  -H "Authorization: Bearer ACCESS_TOKEN"

Delete a item from a list

Scopes

lists

HTTP Request

DELETE https://api.twine.fm/lists/{list_id}/items/{item_id}

URL Parameters

Parameter Required Description Default
list_id
string
Yes The id of the list
item_id
string
Yes The id of the item

Messages

All messages are private and can only be accessed by the authenticated user. Trying to access another users messages will result in a 404 error response.

All message endpoints can have an optional include query parameter. This can be used to get additional information about the message, such as the sender and receiver user information.

Parameter Required Description Default
include
string
No Include additional information about the message or thread.
Available includes: sender, receiver

sender: Provides the user that sent the message.
receiver: Provides the user that received the message.

Get all message threads

Example Request:

curl "https://api.twine.fm/threads"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "threads": [
    {
      "id": 2,
      "sender_id": 1,
      "receiver_id": 2,
      "receiver_viewed": "2015-12-01T00:00:00+0000",
      "message": {
        "id": 1,
        "text": "foo"
      }
    }
  ]
}

Get all the message threads for a user. By default the latest message is include in the thread data. Results are paginated

If the receiving user has read the message then receiver_viewed will be set to the timestamp they first read/saw the message, else it will be set to null.

Scopes

messages

HTTP Request

GET https://api.twine.fm/threads

URL Parameters

Parameter Required Description Default
page
integer
No Page 1
limit
integer
No Limit the number of message threads
Max: 100
10

Send a message

Example Request:

curl "https://api.twine.fm/messages"
  -X POST
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "id": 2,
  "text": "bar"
}

Send a message to a user.

Scopes

messages

HTTP Request

POST https://api.twine.fm/messages

Request Parameters

Parameter Required Description Default
receiver_id
integer
Yes The id of the user who the message is bing sent to
message
string
Yes The message it self.
Must be between 1 and 1000 characters

Get a message thread

Example Request:

curl "https://api.twine.fm/threads/2"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "threads": [
    {
      "id": 2,
      "sender_id": 1,
      "receiver_id": 2,
      "receiver_viewed": "2015-12-01T00:00:00+0000",
      "message": {
        "id": 1,
        "text": "foo"
      }
    },
    {
      "id": 2,
      "sender_id": 2,
      "receiver_id": 1,
      "receiver_viewed": "2015-12-01T00:00:00+0000",
      "message": {
        "id": 2,
        "text": "bar"
      }
    }
  ]
}

Get a message thread between 2 users. Results are paginated

Scopes

messages

HTTP Request

GET https://api.twine.fm/threads/{thread_id}

URL Parameters

Parameter Required Description Default
thread_id
integer
Yes Id if the thread to get
page
integer
No Page 1
limit
integer
No Limit the number of message threads
Max: 100
10

Delete a message

Example Request:

curl "https://api.twine.fm/messages/1"
  -X DELETE
  -H "Authorization: Bearer ACCESS_TOKEN"

Delete a message.

Scopes

messages

HTTP Request

DELETE https://api.twine.fm/messages/{message_id}

URL Parameters

Parameter Required Description Default
message_id
integer
Yes Id of the message to delete (not thread!)

Notices

All notices are public but can only be accessed by an authenticated user.

All notices endpoints can have an optional include query parameter. This can be used to get additional information about the notice, such as the user information.

Parameter Required Description Default
include
string
No Include additional information about the message or thread.
Available includes: user

user: Provides the user that of the notice.

Get all collaboration notices

Example Request:

curl "https://api.twine.fm/notices/collaboration"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "collaborations": [
    {
      "id": 2,
      "text": "Looking for a DJ for an amazing project I have lined up",
      "roles": [
        "DJ"
      ],
      "timestamp": "2015-12-01T00:00:00+0000",
      "expires_at": "2015-12-07T00:00:00+0000",
      "active": true,
      "amount": 3000,
      "currency": "gbp",
      "links": {
        "main": "https://www.twine.fm/collaborate/b6c6g1",
        "short": "http://clw.ee/b6c6g1"
      }
    },
    {
      "id": 1,
      "text": "Looking for a producer for an amazing project I have lined up",
      "roles": [
        "Music Producer"
      ],
      "timestamp": "2015-12-01T00:00:00+0000",
      "expires_at": "2015-12-07T00:00:00+0000",
      "active": true,
      "amount": 1000,
      "currency": "gbp",
      "links": {
        "main": "https://www.twine.fm/collaborate/b6c6g0",
        "short": "http://clw.ee/b6c6g0"
      }
    }
  ]
}

Get all collaboration notices. Results are paginated.

HTTP Request

GET https://api.twine.fm/notices/collaboration

URL Parameters

Parameter Required Description Default
page
integer
No Page 1
limit
integer
No Limit the number of results
Max: 100
10

Get a collaboration notice

Example Request:

curl "https://api.twine.fm/notices/collaboration/1"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "id": 1,
  "text": "Looking for a producer for an amazing project I have lined up",
  "roles": [
    "Music Producer"
  ],
  "timestamp": "2015-12-01T00:00:00+0000",
  "expires_at": "2015-12-07T00:00:00+0000",
  "active": true,
  "amount": 1000,
  "currency": "gbp",
  "links": {
    "main": "https://www.twine.fm/collaborate/b6c6g0",
    "short": "http://clw.ee/b6c6g0"
  }
}

Get a collaboration notice.

HTTP Request

GET https://api.twine.fm/notices/collaboration/{collaboration_id}

URL Parameters

Parameter Required Description Default
collaboration_id
integer
Yes The id of the collaboration notice

Add a new collaboration notice

Example Request:

curl "https://api.twine.fm/notices/collaboration"
  -X POST
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d text="Looking for a DJ for an amazing project I have lined up"
  -d roles[]="DJ"

Example Response:

{
  "id": 2,
  "text": "Looking for a DJ for an amazing project I have lined up",
  "roles": [
    "DJ"
  ],
  "timestamp": "2015-12-01T00:00:00+0000",
  "expires_at": "2015-12-07T00:00:00+0000",
  "active": true,
  "amount": 0,
  "currency": null,
  "links": {
    "main": "https://www.twine.fm/collaborate/b6c6g1",
    "short": "http://clw.ee/b6c6g1"
  }
}

Add a new collaboration notice board post.

HTTP Request

POST https://api.twine.fm/notices/collaboration

Request Parameters

Parameter Required Description Default
text
string
Yes Text of the collaboration board post.
Must be between 1 and 140 characters.
roles
array
Yes The roles looking for.
Max items: 1.
amount
integer
No The amount willing to pay for the role.
currency
string
No The currency the amount is in.
Required with amount. Must be one of: “gbp”, “usd”, “eur”

Update a collaboration notice

Example Request:

curl "https://api.twine.fm/notices/collaboration/1"
  -X PATCH
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d text="Looking for a DJ for an amazing project I have lined up"
  -d roles[]="DJ"

Example Response:

{
  "id": 1,
  "text": "Looking for a DJ for an amazing project I have lined up",
  "roles": [
    "DJ"
  ],
  "timestamp": "2015-12-01T00:00:00+0000",
  "expires_at": "2015-12-07T00:00:00+0000",
  "active": true,
  "amount": 0,
  "currency": null,
  "links": {
    "main": "https://www.twine.fm/collaborate/b6c6g0",
    "short": "http://clw.ee/b6c6g0"
  }
}

Update a collaboration notice board post.

HTTP Request

POST https://api.twine.fm/notices/collaboration/{collaboration_id}

URL Parameters

Parameter Required Description Default
collaboration_id
integer
Yes The id of the collaboration notice

Request Parameters

Parameter Required Description Default
text
string
No Text of the collaboration board post.
Must be between 1 and 140 characters.
roles
array
No The roles looking for.
Max items: 1.
amount
integer
No The amount willing to pay for the role.
currency
string
No The currency the amount is in.
Required with amount. Must be one of: “gbp”, “usd”, “eur”

Delete a collaboration notice

Example Request:

curl "https://api.twine.fm/notices/collaboration/1"
  -X DELETE
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d success="1"

Delete a collaboration notice.

HTTP Request

DELETE https://api.twine.fm/notices/collaboration/{collaboration_id}

URL Parameters

Parameter Required Description Default
collaboration_id
integer
Yes The id of the collaboration notice

Request Parameters

Parameter Required Description Default
success
boolean
No Whether the post was successful or not

Get all suggested notice roles

Example Request:

curl "https://api.twine.fm/notices/collaboration/roles"
  -X GET
  -H "Authorization: Bearer ACCESS_TOKEN"

Example Response:

{
  "roles": [
    "Accountant",
    "DJ"
  ]
}

Get all suggested notice roles currently on the notice board for filtering.

HTTP Request

GET https://api.twine.fm/notices/collaboration/roles