snarl.de

Friendica API

The Friendica API aims to be compatible to 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 occour in API call, an HTTP error code is returned, with an error message Usually: - 400 Bad Request: if parameter are missing or items can't be found - 403 Forbidden: if authenticated user is missing - 405 Method Not Allowed: if API was called with invalid method, eg. GET when API require POST - 501 Not Implemented: if requested API doesn't exists - 500 Internal Server Error: on other error contitions

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: * JSON return as defined for Twitter API not yet implemented * on friendica_verbose=true: JSON return {"result":"ok","message":"message deleted"}

On error: HTTP 400 BadRequest * on friendica_verbose=true: different JSON returns {"result":"error","message":"xyz"}


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 followers of other users.


friends/ids (*; AUTH)

Parameters

Unsupported parameters

Friendica doesn't allow showing friends of other users.


help/test (*)


media/upload (POST,PUT; AUTH)

Parameters


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


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/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


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.


users/search (*)

Parameters

Unsupported parameters


users/show (*)

Parameters

Unsupported parameters

Friendica doesn't allow showing friends of other users.

Implemented API calls (not compatible with other APIs)


friendica/activity/

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-GG HH:MM:SS)",
        "edited": "date(YYYY-MM-GG 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-GG HH:MM:SS)</created>
        <edited>date(YYYY-MM-GG 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/direct_messages_setseen (GET; AUTH)

Parameters

Return values

On success: * JSON return {"result":"ok","message":"message set to seen"}

On error: * different JSON returns {"result":"error","message":"xyz"}


friendica/direct_messages_search (GET; AUTH)

Parameters

Return values

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

On success: * JSON return {"success":"true","search_results": array of found messages} * JSOn return {"success":"false","search_results":"nothing found"}

On error: * different JSON returns {"result":"error","message":"searchstring not specified"}


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 provided HTTP 400 Bad Request: if given profile_id is not in db or not assigned to authenticated user

General description of profile data in API returns: * profile_id * profile_name * is_default: true if this is the public profile * hide_friends: true if friends are hidden * profile_photo * profile_thumb * publish: true if published on the server's local directory * net_publish: true if published to global_dir * description ... homepage: different data fields from 'profile' table in database * users: array with the users allowed to view this profile (empty if is_default=true)


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 aren't implemented neither in Friendica nor in GNU Social:



Usage Examples

BASH / cURL

Betamax has documentated some example API usage from a [bash script](https://en.wikipedia.org/wiki/Bash_(Unix_shell) employing curl (see his posting).

/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 RSStoFriedika 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.

Help us to cover the server costs for snarl.de
Click here to lend your support to: Help us to cover the server costs for snarl.de!