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:
- 400 Bad Request: if parameters are missing or items can't be found
- 403 Forbidden: if the authenticated user is missing
- 405 Method Not Allowed: if API was called with an invalid method, eg. GET when API require POST
- 501 Not Implemented: if the requested API doesn't exist
- 500 Internal Server Error: on other error conditions

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

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 (*)

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.

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:
* JSON return: returns the updated user details (see account/verify_credentials)

On error:
* 403 FORBIDDEN: if not authenticated
* 400 BADREQUEST: "no media data submitted", "profile_id not available"
* 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
"image size exceeds Friendica Config setting (uploaded size: x)",
"unable to process image data",
"image upload failed"

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-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:
* JSON return {"result":"deleted","message":"album 'xyz' with all containing photos has been deleted."}

On error:
* 403 FORBIDDEN: if not authenticated
* 400 BADREQUEST: "no albumname specified", "album not available"
* 500 INTERNALSERVERERROR: "problem with deleting item occured", "unknown error - deleting from database failed"

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

Parameters

changes the album name to album_new for all photos in album

Return values

On success:
* JSON return {"result":"updated","message":"album 'abc' with all containing photos has been renamed to 'xyz'."}

On error:
* 403 FORBIDDEN: if not authenticated
* 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available"
* 500 INTERNALSERVERERROR: "unknown error - updating in database failed"

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:
* new photo uploaded: JSON return with photo data (see friendica/photo)
* photo updated - changed photo data: JSON return with photo data (see friendica/photo)
* photo updated - changed info: JSON return {"result":"updated","message":"Image id 'xyz' has been updated."}
* photo updated - nothing changed: JSON return {"result":"cancelled","message":"Nothing to update for image id 'xyz'."}

On error:
* 403 FORBIDDEN: if not authenticated
* 400 BADREQUEST: "no albumname specified", "no media data submitted", "photo not available", "acl data invalid"
* 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
"image size exceeds Friendica Config setting (uploaded size: x)",
"unable to process image data",
"image upload failed",
"unknown error - uploading photo failed, see Friendica log for more information",
"unknown error - update photo entry in database failed",
"unknown error - this error on uploading or updating a photo should never happen"

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:
* JSON return {"result":"deleted","message":"photo with id 'xyz' has been deleted from server."}

On error:
* 403 FORBIDDEN: if not authenticated
* 400 BADREQUEST: "no photo_id specified", "photo not available"
* 500 INTERNALSERVERERROR: "unknown error on deleting photo", "problem with deleting items occurred"

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 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:
* 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 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 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.