Flattr Developer Platform

Things

The Thing object

FieldTypePermissionDescription
typestringObject type, set to thing.
resourcestringURL to the API resource
linkstringURL to user on Flattr.com website
idintID of the thing
urlstringURL the thing is pointing to
flattrsintNumber of flattrs
flattrs_user_countintNumber of user who have flattred
titlestringTitle of the thing
descriptionstringDescription of the thing
tagsarrayArray with tags as strings
languagestringLangauge
categorystringCategory
created_atintFormat is unixtime
ownerhashContains either a user object or a mini user object (default).
hiddenboolHidden or not in listings. Example, API search and Catalog.
imagestringURL to thing image
flattredboolauthenticatedHas the authenticated user flattred the thing
last_flattr_atintownerLast time flattred. Format is unixtime. Only available if the authenticated user owns the thing.
updated_atintownerLast time updated. Format is unixtime. Only available if the authenticated user owns the thing.

The Mini Thing object

FieldTypePermissionDescription
typestringObject type, set to thing.
resourcestringURL to the API resource
linkstringURL to user on Flattr.com website
idintID of the thing
urlstringURL the thing is pointing to
flattrsintNumber of flattrs
titlestringTitle of the thing
imagestringURL to thing image

List a users things

Parameters
Request
GET https://api.flattr.com/rest/v2/users/:username/things
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
[
  {
    "type": "thing",
    "resource": "https://api.flattr.com/rest/v2/things/423405",
    "link": "https://flattr.com/thing/423405",
    "id": 423405,
    "url": "http://blog.flattr.net/2011/10/api-v2-beta-out-whats-changed/",
    "language": "en_GB",
    "category": "text",
    "owner": {
      "type": "user",
      "resource": "https://api.flattr.com/rest/v2/users/flattr",
      "link": "https://flattr.com/profile/flattr",
      "id": "3bpQBK",
      "username": "flattr"
    },
    "hidden": false,
    "image": "http://flattr.com/thing/image/4/2/3/4/0/5/medium.png",
    "created_at": 1319704532,
    "tags": [
      "api"
    ],
    "flattrs": 8,
    "description": "We have been working hard to deliver a great experience for developers and tried to build a good foundation for easily add new features. The API will remain in beta for a while for us to kill quirks and refine some of the resources, this means there might be big changes without notice for ...",
    "title": "API v2 beta out - what's changed?",
    "flattred": false,
    "subscribed": true
  }
]
Errors

List a authenticated users things

Authorization needed

Parameters
Request
GET https://api.flattr.com/rest/v2/user/things
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
[
  {
    "type": "thing",
    "resource": "https://api.flattr.com/rest/v2/things/423405",
    "link": "https://flattr.com/thing/423405",
    "id": 423405,
    "url": "http://blog.flattr.net/2011/10/api-v2-beta-out-whats-changed/",
    "language": "en_GB",
    "category": "text",
    "owner": {
      "type": "user",
      "resource": "https://api.flattr.com/rest/v2/users/flattr",
      "link": "https://flattr.com/profile/flattr",
      "id": "3bpQBK",
      "username": "flattr"
    },
    "hidden": false,
    "image": "http://flattr.com/thing/image/4/2/3/4/0/5/medium.png",
    "created_at": 1319704532,
    "tags": [
      "api"
    ],
    "flattrs": 8,
    "description": "We have been working hard to deliver a great experience for developers and tried to build a good foundation for easily add new features. The API will remain in beta for a while for us to kill quirks and refine some of the resources, this means there might be big changes without notice for ...",
    "title": "API v2 beta out - what's changed?",
    "flattred": false,
    "subscribed": true
  }
]
Errors

Get a thing

Parameters
Request
GET https://api.flattr.com/rest/v2/things/:id
Example response without an access token (public)
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
{
  "type": "thing",
  "resource": "https://api.flattr.com/rest/v2/things/423405",
  "link": "https://flattr.com/thing/423405",
  "id": 423405,
  "url": "http://blog.flattr.net/2011/10/api-v2-beta-out-whats-changed/",
  "language": "en_GB",
  "category": "text",
  "owner": {
    "type": "user",
    "resource": "https://api.flattr.com/rest/v2/users/flattr",
    "link": "https://flattr.com/profile/flattr",
    "id": "3bpQBK",
    "username": "flattr"
  },
  "hidden": false,
  "image": "http://flattr.com/thing/image/4/2/3/4/0/5/medium.png",
  "created_at": 1319704532,
  "tags": [
    "api"
  ],
  "flattrs": 8,
  "description": "We have been working hard to deliver a great experience for developers and tried to build a good foundation for easily add new features. The API will remain in beta for a while for us to kill quirks and refine some of the resources, this means there might be big changes without notice for ...",
  "title": "API v2 beta out - what's changed?"
}
Errors
Example response when resource owner don't own the thing
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
{
  "type": "thing",
  "resource": "https://api.flattr.com/rest/v2/things/423405",
  "link": "https://flattr.com/thing/423405",
  "id": 423405,
  "url": "http://blog.flattr.net/2011/10/api-v2-beta-out-whats-changed/",
  "language": "en_GB",
  "category": "text",
  "owner": {
    "type": "user",
    "resource": "https://api.flattr.com/rest/v2/users/flattr",
    "link": "https://flattr.com/profile/flattr",
    "id": "3bpQBK",
    "username": "flattr"
  },
  "hidden": false,
  "image": "http://flattr.com/thing/image/4/2/3/4/0/5/medium.png",
  "created_at": 1319704532,
  "tags": [
    "api"
  ],
  "flattrs": 8,
  "description": "We have been working hard to deliver a great experience for developers and tried to build a good foundation for easily add new features. The API will remain in beta for a while for us to kill quirks and refine some of the resources, this means there might be big changes without notice for ...",
  "title": "API v2 beta out - what's changed?",
  "flattred": false,
  "subscribed": true
}
Example response when resource owner owns the thing
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
{
  "type": "thing",
  "resource": "https://api.flattr.com/rest/v2/things/423405",
  "link": "https://flattr.com/thing/423405",
  "id": 423405,
  "url": "http://blog.flattr.net/2011/10/api-v2-beta-out-whats-changed/",
  "language": "en_GB",
  "category": "text",
  "owner": {
    "type": "user",
    "resource": "https://api.flattr.com/rest/v2/users/flattr",
    "link": "https://flattr.com/profile/flattr",
    "id": "3bpQBK",
    "username": "flattr"
  },
  "hidden": false,
  "image": "http://flattr.com/thing/image/4/2/3/4/0/5/medium.png",
  "created_at": 1319704532,
  "tags": [
    "api"
  ],
  "flattrs": 8,
  "description": "We have been working hard to deliver a great experience for developers and tried to build a good foundation for easily add new features. The API will remain in beta for a while for us to kill quirks and refine some of the resources, this means there might be big changes without notice for ...",
  "title": "API v2 beta out - what's changed?",
  "last_flattr_at": 1320262599,
  "updated_at": 0,
  "flattred": false,
  "subscribed": true
}

Get multiple things

Parameters
Request
GET https://api.flattr.com/rest/v2/things/:id,:id
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
[
  {
    "type": "thing",
    "resource": "https://api.flattr.com/rest/v2/things/423405",
    "link": "https://flattr.com/thing/423405",
    "id": 423405,
    "url": "http://blog.flattr.net/2011/10/api-v2-beta-out-whats-changed/",
    "language": "en_GB",
    "category": "text",
    "owner": {
      "type": "user",
      "resource": "https://api.flattr.com/rest/v2/users/flattr",
      "link": "https://flattr.com/profile/flattr",
      "id": "3bpQBK",
      "username": "flattr"
    },
    "hidden": false,
    "image": "http://flattr.com/thing/image/4/2/3/4/0/5/medium.png",
    "created_at": 1319704532,
    "tags": [
      "api"
    ],
    "flattrs": 8,
    "description": "We have been working hard to deliver a great experience for developers and tried to build a good foundation for easily add new features. The API will remain in beta for a while for us to kill quirks and refine some of the resources, this means there might be big changes without notice for ...",
    "title": "API v2 beta out - what's changed?"
  },
  {
    "type": "thing",
    "resource": "https://api.flattr.dev/rest/v2/things/450287",
    "link": "https://flattr.dev/thing/450287",
    "id": 450287,
    "url": "https://github.com/simon/flattr",
    "language": "en_GB",
    "category": "software",
    "owner": {
      "type": "user",
      "resource": "https://api.flattr.dev/rest/v2/users/smgt",
      "link": "https://flattr.dev/profile/smgt",
      "id": "l8ENA7",
      "username": "smgt"
    },
    "hidden": 0,
    "image": "",
    "created_at": 1323614098,
    "tags": [
      "gem",
      "ruby",
      "programming",
      "opensource",
      "flattr",
      "api"
    ],
    "flattrs": 7,
    "description": "A ruby gem wrapping Flattrs API.",
    "title": "Ruby gem wrapping Flattrs API"
  }
]
Errors

Check if a thing exists

Parameters
Request
GET https://api.flattr.com/rest/v2/things/lookup/?url=:url
Example response when url was found
HTTP/1.1 302 Found
Content-Type: application/json;charset=utf-8
Location: https://api.flattr.com/rest/v2/things/423405
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
{
  "message": "found",
  "location": "https://api.flattr.com/rest/v2/things/423405"
}
Example response when url was not found
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
{
  "message": "not_found",
  "description": "No thing was found"
}
Example request to lookup a autosubmit URL

The lookup resource can now lookup autosubmit URLs, you will need to url encode the data you pass into the url parameter. For more information check out the auto submit documentation.

GET https://api.flattr.com/rest/v2/things/lookup/?url=http://flattr.com/submit/auto?url=http://blog.flattr.net/2011/10/api-v2-beta-out-whats-changed/&user_id=flattr
Example response to autosubmit URL
HTTP/1.1 302 Found
Content-Type: application/json;charset=utf-8
Location: https://api.flattr.com/rest/v2/things/423405
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
{
  "message": "found",
  "location": "https://api.flattr.com/rest/v2/things/423405"
}
Errors

Create a thing

Authorization needed

Scope required: thing

Parameters

Request
POST https://api.flattr.com/rest/v2/things
Request body
{
  "url": "http://developers.flattr.net"
}
Example response
HTTP/1.1 201 Created
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
{
  "id": 431547,
  "link": "https://api.flattr.com/rest/v2/things/431547",
  "message": "ok",
  "description": "Thing was created successfully"
}
Errors

example error when an invalid url is submitted

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
{
  "error": "validation",
  "error_description": "Invalid url",
  "error_uri": "http://developers.flattr.net/api"
}

Update a thing

Currently we are having problems with the PATCH request. To work around this problem you should do a POST request instead of an PATCH and include the parameter _method with with the value patch.

Authorization needed

Scope required: thing

Parameters

Request
PATCH https://api.flattr.com/rest/v2/things/:id
Request body
{
  "title": "API v2 documentation"
}
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
{
  "message": "ok",
  "description": "Thing was updated correctly"
}
Errors

Delete a thing

Authorization needed

Scope required: thing

Request
DELETE https://api.flattr.com/rest/v2/things/:id
Example response
HTTP/1.1 204 No Content
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
Errors

Search things

Parameters
Tags

Tags support a syntax to do advanced tag lookups. It supports | ( OR ), ! ( NOT ) and & ( AND ).

Example: Search all things containing the tag game or games but not software would yield game | games ! software.

Example: Search all things containing the tags photo and flickr but not any illustrations. photo & flickr ! illustrations

Remember to URL encode the tags or else you might be getting problems with the ampersand &. For example photos & travel & iphone !flickr would convert to photos+%26+travel+%26+iphone+!flickr.

Request
GET https://api.flattr.com/rest/v2/things/search
Example request

Search after flattr in the software category with the ruby tag

GET https://api.flattr.com/rest/v2/things/search?query=flattr&category=software&tags=ruby
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Current: 1
X-RateLimit-Reset: 1342521939
{
  "total_items": 1,
  "items": 1,
  "page": 1,
  "things": [
    {
      "type": "thing",
      "resource": "https://api.flattr.com/rest/v2/things/423405",
      "link": "https://flattr.com/thing/423405",
      "id": 423405,
      "url": "http://blog.flattr.net/2011/10/api-v2-beta-out-whats-changed/",
      "language": "en_GB",
      "category": "text",
      "owner": {
        "type": "user",
        "resource": "https://api.flattr.com/rest/v2/users/flattr",
        "link": "https://flattr.com/profile/flattr",
        "id": "3bpQBK",
        "username": "flattr"
      },
      "hidden": false,
      "image": "http://flattr.com/thing/image/4/2/3/4/0/5/medium.png",
      "created_at": 1319704532,
      "tags": [
        "api"
      ],
      "flattrs": 8,
      "description": "We have been working hard to deliver a great experience for developers and tried to build a good foundation for easily add new features. The API will remain in beta for a while for us to kill quirks and refine some of the resources, this means there might be big changes without notice for ...",
      "title": "API v2 beta out - what's changed?"
    }
  ]
}
Visit Flattr.com to learn more about Flattr.