Flattr Developer Platform

The Flattr object

List a users flattrs

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 thing and user objects instead of small

Request

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

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": "flattr",
    "thing": {
      "type": "thing",
      "resource": "https://api.flattr.com/rest/v2/things/313733",
      "link": "https://flattr.com/thing/313733",
      "id": 313733,
      "url": "https://flattr.com/profile/gnuproject",
      "title": "GNU's not Unix!",
      "image": "https://flattr.com/thing/image/3/1/3/7/3/3/medium.png",
      "flattrs": 3,
      "owner": {
        "type": "user",
        "resource": "https://api.flattr.com/rest/v2/users/gnuproject",
        "link": "https://flattr.com/user/gnuproject",
        "username": "gnuproject"
      }
    },
    "owner": {
      "type": "user",
      "resource": "https://api.flattr.com/rest/v2/users/qzio",
      "link": "https://flattr.com/user/qzio",
      "username": "qzio"
    },
    "created_at": 1316697578
  }
]

If the response header is 200 OK but the response is empty there is two possible reasons. One is that the user have choosen to hide what he/she flattrs. The other is because that user haven't flattred anything yet.

Errors

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

List the authenticated users flattrs

Parameters

• count ( Optional ) - Number of records to receive
• page ( Optional ) - Page of results to retreive
• full ( Optional ) - Receive full thing and user objects instead of small

Request

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

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": "flattr",
    "thing": {
      "type": "thing",
      "resource": "https://api.flattr.com/rest/v2/things/313733",
      "link": "https://flattr.com/thing/313733",
      "id": 313733,
      "url": "https://flattr.com/profile/gnuproject",
      "title": "GNU's not Unix!",
      "image": "https://flattr.com/thing/image/3/1/3/7/3/3/medium.png",
      "flattrs": 3,
      "owner": {
        "type": "user",
        "resource": "https://api.flattr.com/rest/v2/users/gnuproject",
        "link": "https://flattr.com/user/gnuproject",
        "username": "gnuproject"
      }
    },
    "owner": {
      "type": "user",
      "resource": "https://api.flattr.com/rest/v2/users/qzio",
      "link": "https://flattr.com/user/qzio",
      "username": "qzio"
    },
    "created_at": 1316697578
  }
]

Errors

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

List a things flattrs

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 thing and user objects instead of small

Request

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

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": "flattr",
    "thing": {
      "type": "thing",
      "resource": "https://api.flattr.com/rest/v2/things/313733",
      "link": "https://flattr.com/thing/313733",
      "id": 313733,
      "url": "https://flattr.com/profile/gnuproject",
      "title": "GNU's not Unix!",
      "image": "https://flattr.com/thing/image/3/1/3/7/3/3/medium.png",
      "flattrs": 3,
      "owner": {
        "type": "user",
        "resource": "https://api.flattr.com/rest/v2/users/gnuproject",
        "link": "https://flattr.com/user/gnuproject",
        "username": "gnuproject"
      }
    },
    "owner": {
      "type": "user",
      "resource": "https://api.flattr.com/rest/v2/users/qzio",
      "link": "https://flattr.com/user/qzio",
      "username": "qzio"
    },
    "created_at": 1316697578
  }
]

Errors

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

Flattr a thing

Scope required: flattr

Request

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

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 successfully flattred",
  "thing": {
    "type": "thing",
    "resource": "https://api.flattr.com/rest/v2/things/423405",
    "link": "https://flattr.com/thing/423405",
    "id": 423405,
    "flattrs": 3,
    "url": "http://blog.flattr.net/2011/10/api-v2-beta-out-whats-changed/",
    "title": "API v2 beta out - what's changed?",
    "image": "https://flattr.com/thing/image/4/2/3/4/0/5/medium.png"
  }
}

Errors

• flattr_once (HTTP 403) - The current user have already flattred the thing
• flattr_owner (HTTP 403) - User is the owner of the thing
• no_means (HTTP 401) - Current user don't have enough means to flattr
• not_found (HTTP 404) - Thing does not exist
• invalid_request (HTTP 400) - Request is not valid

Flattr a URL

Scope required: flattr

The flattr resource flattrs flattrable URL:s. Flattrable URL:s are those already registered with Flattr, those that we support discovering ownership data of and those contained within an auto-submit URL together with the metadata needed to register a new thing.

Discoverable URL:s

We support discovering ownership data from these URL:s.

• GitHub profiles, repositories, commits and gists that isn't owned by an organization.
• SoundCloud profiles, tracks and sets.
• Twitter profiles and tweets.
• Instagram photos.

Auto-submit URL:s

An auto-submit URL contains all necessary metadata for a thing. If the URL in an auto-submit URL isn't registered on Flattr, then it will be created before being then flattred. Auto-submit URL:s are recommended for use in eg. feeds and looks like this: http://flattr.com/submit/auto?url=http%3A%2F%2Fblog.flattr.net%2F2011%2F10%2Fapi-v2-beta-out-whats-changed%2F&user_id=flattr.

Parameters

• url ( Required ) - The URL to flattr or an auto-submit URL containing the URL to flattr

Request

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

{
  "url": "http://flattr.com/submit/auto?url=http%3A%2F%2Fblog.flattr.net%2F2011%2F10%2Fapi-v2-beta-out-whats-changed%2F&user_id=flattr"
}

Example response to autosubmit URL

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 successfully flattred",
  "thing": {
    "type": "thing",
    "resource": "https://api.flattr.com/rest/v2/things/423405",
    "link": "https://flattr.com/thing/423405",
    "id": 423405,
    "flattrs": 3,
    "url": "http://blog.flattr.net/2011/10/api-v2-beta-out-whats-changed/",
    "title": "API v2 beta out - what's changed?",
    "image": "https://flattr.com/thing/image/4/2/3/4/0/5/medium.png"
  }
}

Errors

• flattr_once (HTTP 403) - The current user have already flattred the thing
• flattr_owner (HTTP 403) - User is the owner of the thing
• no_means (HTTP 401) - Current user don't have enough means to flattr
• not_found (HTTP 404) - Thing does not exist
• invalid_request (HTTP 400) - Request is not valid