Things

List a users things

Parameters

count ( Optional ) - Number of records to receive ( default: 30 )
page ( Optional ) - Page of results to retreive ( first page is 1 )
full ( Optional ) - Receive full user object instead of small

Request

GET https://api.flattr.com/rest/v2/users/:username/things

Example response

Status: 200 OK
Content-type: application/json;charset=utf-8
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "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",
    "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
}

Errors

not_found (404 Not Found) - The requested user could not be found

List a authenticated users things

Authorization needed

Parameters

count ( Optional ) - Number of records to receive ( default: 30)
page ( Optional ) - Page of results to retreive ( first page is 1 )
full ( Optional ) - Receive full user object instead of small

Request

GET https://api.flattr.com/rest/v2/user/things

Example response

Status: 200 OK
Content-type: application/json;charset=utf-8
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

[
  {
    "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",
      "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
  }
]

Errors

unauthorized (401 Unauthorized) - You are unauthorized to access the resource (no token?)

Get a thing

Parameters

full ( Optional ) - Receive full user object instead of small

Request

GET https://api.flattr.com/rest/v2/things/:id

Example response without an access token (public)

Status: 200 OK
Content-type: application/json;charset=utf-8
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "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",
    "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

not_found (404 Not Found) - the thing can not be found

Example response when resource owner don't own the thing

Status: 200 OK
Content-type: application/json;charset=utf-8
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "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",
    "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
}

Example response when resource owner owns the thing

Status: 200 OK
Content-type: application/json;charset=utf-8
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "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",
    "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
}

Get multiple things

Parameters

id ( Optional ) - A list of thing ids you want separated with a comma (,).
full ( Optional ) - Receive full user object instead of small

Request

GET https://api.flattr.com/rest/v2/things/:id,:id

Example response

Status: 200 OK
Content-type: application/json;charset=utf-8
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

[
  {
    "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",
      "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",
      "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

not_found (404 Not Found) - The requested thing(s) could not be found"

Check if a thing exists

Parameters

url (Optional) - The URL you want to lookup

Request

GET https://api.flattr.com/rest/v2/things/lookup/?url=:url

Example response when url was found

Status: 302 Found
Content-type: application/json;charset=utf-8
Location: https://api.flattr.com/rest/v2/things/423405
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "message": "found",
  "location": "https://api.flattr.com/rest/v2/things/423405"
}

Example response when url was not found

Status: 404 Not Found
Content-type: application/json;charset=utf-8
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "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

Status: 302 Found
Content-type: application/json;charset=utf-8
Location: https://api.flattr.com/rest/v2/things/423405
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "message": "found",
  "location": "https://api.flattr.com/rest/v2/things/423405"
}

Errors

validation (400 Bad Request) - Owner mismatch. Current thing owned by other account.

Create a thing

Authorization needed

Scope required: thing

Parameters

url ( Required ) - string URL to submit.
title ( Optional ) - string Title of the new thing.
description ( Optional ) - string Description text of the new thing.
category ( Optional ) - string Default is "rest"
language ( Optional ) - string Default is "en_GB"
tags ( Optional ) - string Comma separated list of tags.
hidden ( Optional ) - boolean Default is "false"

Request

POST https://api.flattr.com/rest/v2/things

Request body

{
  "url": "http://developers.flattr.net"
}

Example response

Status: 201 Created
Content-type: application/json;charset=utf-8
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "id": 431547,
  "link": "https://api.flattr.com/rest/v2/things/431547",
  "message": "ok",
  "description": "Thing was created successfully"
}

Errors

validation (400 Bad Request) - The information you submitted did not validate

example error when an invalid url is submitted

Status: 400 Bad Request
Content-type: application/json;charset=utf-8
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "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

title ( Optional ) - string Title of the new thing.
description ( Optional ) - string Description text of the new thing.
category ( Optional ) - string
language ( Optional ) - string
tags ( Optional ) - string Comma separated list of tags.
hidden ( Optional ) - boolean
_method ( Required ) - must be set to patch

Request

PATCH https://api.flattr.com/rest/v2/things/:id

Request body

{
  "title": "API v2 documentation"
}

Example response

Status: 200 OK
Content-type: application/json;charset=utf-8
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "message": "ok",
  "description": "Thing was updated correctly"
}

Errors

validation (400 Bad Request) - The information you submitted did not validate

Delete a thing

Authorization needed

Scope required: thing

Request

DELETE https://api.flattr.com/rest/v2/things/:id

Example response

Status: 204 No Content
Content-type: application/json;charset=utf-8
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Errors

forbidden (403 Forbidden) - Cannot delete the thing. Maby it's not you thing or the scope thing is missing.

Search things

Parameters

query (Optional) - string Free text search string
url (Optional) - string Filter by url
tags (Optional) - string Filter by tags, see syntax below
language (Optional) - string Filter by language
category (Optional) - string Filter by category. If you wan't to search more than one category you can separate them with a , (comma).
user (Optional) - string Filter by username
sort (Optional) - string Sort by trend, flattrs (all time), flattrs_month, flattrs_week, flattrs_day or relevance (default)
page (Optional) - integer The result page to show
count (Optional) - integer Number of items per page
full ( Optional ) - Receive full user object instead of small

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

Status: 200 OK
Content-type: application/json;charset=utf-8
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "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",
        "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?"
    }
  ]
}

Flattr Developer Platform

List a users things

Parameters

Request

Example response

Errors

List a authenticated users things

Parameters

Request

Example response

Errors

Get a thing

Parameters

Request

Example response without an access token (public)

Errors

Example response when resource owner don't own the thing

Example response when resource owner owns the thing

Get multiple things

Parameters

Request

Example response

Errors

Check if a thing exists

Parameters

Request

Example response when url was found

Example response when url was not found

Example request to lookup a autosubmit URL

Example response to autosubmit URL

Errors

Create a thing

Request

Request body

Example response

Errors

Update a thing

Request

Request body

Example response

Errors

Delete a thing

Request

Example response

Errors

Search things

Parameters

Tags

Request

Example request

Example response