social.bitrecycler.de

Friendica API

The Friendica API aims to be compatible with the GNU Social API and the Twitter API.

Please refer to the linked documentation for further information.

Implemented API calls

General

HTTP Method

API endpoints can restrict the method used to request them. Using an invalid method results in HTTP error 405 "Method Not Allowed".

In this document, the required method is listed after the endpoint name. "*" means every method can be used.

Auth

Friendica supports basic http auth and OAuth 1 to authenticate the user to the api.

OAuth settings can be added by the user in web UI under /settings/oauth/

In this document, endpoints which requires auth are marked with "AUTH" after endpoint name

Unsupported parameters

Different behaviour

Return values

Errors

When an error occurs in API call, an HTTP error code is returned, with an error message Usually:

Error body is

json:

    {
        "error": "Specific error message",
        "request": "API path requested",
        "code": "HTTP error code"
    }

xml:

    <status>
        <error>Specific error message</error>
        <request>API path requested</request>
        <code>HTTP error code</code>
    </status>

account/rate_limit_status (*; AUTH)


account/verify_credentials (*; AUTH)

Parameters


conversation/show (*; AUTH)

Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.

Parameter

Unsupported parameters


direct_messages (*; AUTH)

Parameters

Unsupported parameters


direct_messages/all (*; AUTH)

Parameters


direct_messages/conversation (*; AUTH)

Shows all direct messages of a conversation

Parameters


direct_messages/sent (*; AUTH)

Parameters


direct_messages/new (POST,PUT; AUTH)

Parameters


direct_messages/destroy (POST,DELETE; AUTH)

Parameters

Return values

On success:

On error: HTTP 400 BadRequest


externalprofile/show (*)

Parameters


favorites (*; AUTH)

Parameters

Unsupported parameters

Favorites aren't displayed to other users, so "user_id" and "screen_name" are unsupported. Set this values will result in an empty array.


favorites/create (POST,PUT; AUTH)

Parameters


favorites/destroy (POST,DELETE; AUTH)

Parameters


followers/ids (*; AUTH)

Parameters

Unsupported parameters

Friendica doesn't allow showing the followers of other users.


friends/ids (*; AUTH)

Parameters

Unsupported parameters

Friendica doesn't allow showing the friends of other users.


help/test (*)


lists/ownerships (*; AUTH)

Parameters

Unsupported parameters


lists/destroy (POST; AUTH)

Parameters

Unsupported parameters


lists/create (POST; AUTH)

Parameters

Unsupported parameters


lists/update (POST; AUTH)

Parameters

Unsupported parameters


lists/statuses (*; AUTH)

Parameters

Unsupported parameters


media/upload (POST,PUT; AUTH)

Parameters

Return values

Object of:


oauth/request_token (*)

Parameters

Unsupported parameters


oauth/access_token (*)

Parameters

Unsupported parameters


statuses/destroy (POST,DELETE; AUTH)

Parameters

Unsupported parameters


statuses/followers (*; AUTH)

Parameters


statuses/friends (*; AUTH)

Parameters


blocks/list (*; AUTH)

Parameters

Unsupported parameters


statuses/friends_timeline (*; AUTH)

Parameters

Unsupported parameters


statuses/home_timeline (*; AUTH)

Parameters

Unsupported parameters


statuses/mentions (*; AUTH)

Parameters

Unsupported parameters


statuses/public_timeline (*; AUTH)

Parameters

Unsupported parameters


statuses/networkpublic_timeline (*; AUTH)

Parameters


statuses/replies (*; AUTH)

Parameters

Unsupported parameters


statuses/retweet (POST,PUT; AUTH)

Parameters

Unsupported parameters


statuses/show (*; AUTH)

Parameters

Unsupported parameters


statuses/update, statuses/update_with_media

Parameters

Unsupported parameters


statuses/user_timeline (*; AUTH)

Parameters

Unsupported parameters


Return values for statuses/* api calls

Returned status object is conform to GNU Social/Twitter api.

Friendica adds some addictional fields:

This properties are prefixed with "friendica_" in JSON responses and namespaced under "http://friendi.ca/schema/api/1/" in XML responses

JSON:

[
    {
        // ...
        'friendica_author' : {
            // user object
        },
        'friendica_owner' : {
            // user object
        },
        'friendica_private' : true,
        'friendica_activities': {
            'like': [
                {
                    // user object 
                },
                // ...
            ],
            'dislike': [],
            'attendyes': [],
            'attendno': [],
            'attendmaybe': []
        },
        'friendica_comments': 12
    },
    // ...
]

XML:

<statuses xmlns="http://api.twitter.com" xmlns:statusnet="http://status.net/schema/api/1/" xmlns:friendica="http://friendi.ca/schema/api/1/" xmlns:georss="http://www.georss.org/georss">
  <status>
    <!-- ... -->
    <friendica:owner><!-- user object --></friendica:owner>
    <friendica:private>true</friendica:private>
    <friendica:activities>
        <friendica:like>
        <user>
            <!-- user object -->
        </user>
        <!-- ... --->
        </friendica:like>
        <friendica:dislike/>
        <friendica:attendyes/>
        <friendica:attendno/>
        <friendica:attendmaybe/>
    </friendica:activities> 
    <friendica:comments>21</friendica:comments>
    </status>
    <!-- ... -->
</statuses>

statusnet/config (*)


statusnet/conversation (*; AUTH)

It shows all direct answers (excluding the original post) to a given id.

Parameter


statusnet/version (*)

Unsupported parameters

Friendica doesn't allow showing followers of other users.


search (*; AUTH)

Parameters

Unsupported parameters


search/tweets (*; AUTH)

This is an alias for search.


saved_searches/list (*; AUTH)

This call does not have any parameter.


users/search (*)

Parameters

Unsupported parameters


users/show (*)

Parameters

Unsupported parameters

Friendica doesn't allow showing friends of other users.


users/lookup (*; AUTH)

Parameters

Unsupported parameters


account/update_profile_image (POST; AUTH)

Parameters

uploads a new profile image (scales 4-6) to database, changes default or specified profile to the new photo

Return values

On success:

On error:


account/update_profile (POST; AUTH)

Parameters

Unsupported parameters


friendships/incoming (*; AUTH)

Unsupported parameters

Implemented API calls (not compatible with other APIs)


friendica/activity/[verb]

parameters

Add or remove an activity from an item. 'verb' can be one of:

To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike" Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes". Attend verbs should be used only with event-related items (there is no check at the moment)

Return values

On success: json:

"ok"

xml:

<ok>true</ok>

On error: HTTP 400 BadRequest


friendica/group_show (*; AUTH)

Return all or a specified group of the user with the containing contacts as array.

Parameters

Return values

Array of:


friendica/group_delete (POST,DELETE; AUTH)

delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted.

Parameters

Return values

Array of:


friendica/group_create (POST,PUT; AUTH)

Create the group with the posted array of contacts as members.

Parameters

POST data

JSON data as Array like the result of "users/group_show":

Return values

Array of:


friendica/group_update (POST)

Update the group with the posted array of contacts as members (post all members of the group to the call; function will remove members not posted).

Parameters

POST data

JSON data as array like the result of „users/group_show“:

Return values

Array of:


friendica/notifications (GET)

Return last 50 notification for current user, ordered by date with unseen item on top

Parameters

none

Return values

Array of:


friendica/notifications/seen (POST)

Set note as seen, returns item object if possible

Parameters

id: id of the note to set seen

Return values

If the note is linked to an item, the item is returned, just like one of the "statuses/*_timeline" api.

If the note is not linked to an item, a success status is returned:


friendica/photo (*; AUTH)

Parameters

Returns data of a picture with the given resource. If 'scale' isn't provided, returned data include full url to each scale of the photo. If 'scale' is set, returned data include image data base64 encoded.

possibile scale value are:

An image used as profile image has only scale 4-6, other images only 0-3

Return values

json:

    {
        "id": "photo id"
        "created": "date(YYYY-MM-DD HH:MM:SS)",
        "edited": "date(YYYY-MM-DD HH:MM:SS)",
        "title": "photo title",
        "desc": "photo description",
        "album": "album name",
        "filename": "original file name",
        "type": "mime type",
        "height": "number",
        "width": "number",
        "profile": "1 if is profile photo",
        "link": {
            "<scale>": "url to image"
            ...
        },
        // if 'scale' is set
        "datasize": "size in byte",
        "data": "base64 encoded image data"
    }

xml:

    <photo>
        <id>photo id</id>
        <created>date(YYYY-MM-DD HH:MM:SS)</created>
        <edited>date(YYYY-MM-DD HH:MM:SS)</edited>
        <title>photo title</title>
        <desc>photo description</desc>
        <album>album name</album>
        <filename>original file name</filename>
        <type>mime type</type>
        <height>number</height>
        <width>number</width>
        <profile>1 if is profile photo</profile>
        <links type="array">
        <link type="mime type" scale="scale number" href="image url"/>
            ...
        </links>
    </photo>

friendica/photos/list (*; AUTH)

Returns a list of all photo resources of the logged in user.

Return values

json:

    [
        {
            id: "resource_id",
            album: "album name",
            filename: "original file name",
            type: "image mime type",
            thumb: "url to thumb sized image"
        },
        ...
    ]

xml:

    <photos type="array">
        <photo id="resource_id"
        album="album name"
        filename="original file name"
        type="image mime type">
            "url to thumb sized image"
        </photo>
        ...
    </photos>

friendica/photoalbum/delete (POST,DELETE; AUTH)

Parameters

deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this

Return values

On success:

On error:


friendica/photoalbum/update (POST,PUT; AUTH)

Parameters

changes the album name to album_new for all photos in album

Return values

On success:

On error:


friendica/photo/create (POST; AUTH)

friendica/photo/update (POST; AUTH)

Parameters

both calls point to one function for creating AND updating photos. Saves data for the scales 0-2 to database (see above for scale description). Call adds non-visible entries to items table to enable authenticated contacts to comment/like the photo. Client should pay attention to the fact that updated access rights are not transferred to the contacts. i.e. public photos remain publicly visible if they have been commented/liked before setting visibility back to a limited group. Currently it is best to inform user that updating rights is not the right way to do this, and offer a solution to add photo as a new photo with the new rights instead.

Return values

On success:

On error:


friendica/photo/delete (DELETE; AUTH)

Parameters

deletes a single image with the specified id, is not reversible -> ensure that client is asking user for being sure to do this Sets item table entries for this photo to deleted = 1

Return values

On success:

On error:


friendica/direct_messages_setseen (GET; AUTH)

Parameters

Return values

On success:

On error:


friendica/direct_messages_search (GET; AUTH)

Parameters

Return values

Returns only tested with JSON, XML might work as well.

On success:

On error:


friendica/profile/show (GET; AUTH)

show data of all profiles or a single profile of the authenticated user

Parameters

Return values

On success: Array of:

On error: HTTP 403 Forbidden: when no authentication was provided HTTP 400 Bad Request: if given profile_id is not in the database or is not assigned to the authenticated user

General description of profile data in API returns:


Not Implemented API calls

The following API calls are implemented in GNU Social but not in Friendica: (incomplete)

The following API calls from the Twitter API are not implemented in either Friendica or GNU Social:



Usage Examples

BASH / cURL

/usr/bin/curl -u USER:PASS https://YOUR.FRIENDICA.TLD/api/statuses/update.xml -d source="some source id" -d status="the status you want to post"

Python

The RSStoFriendika code can be used as an example of how to use the API with python. The lines for posting are located at line 21 and following.

def tweet(server, message, group_allow=None): url = server + '/api/statuses/update' urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))

There is also a module for python 3 for using the API.