The Friendica API aims to be compatible to the [GNU Social API](http://wiki.gnusocial.de/gnusocial:api) and the [Twitter API](https://dev.twitter.com/rest/public).
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
* cursor: Not implemented in GNU Social
* trim_user: Not implemented in GNU Social
* contributor_details: Not implemented in GNU Social
* place_id: Not implemented in GNU Social
* display_coordinates: Not implemented in GNU Social
* include_rts: To-Do
* include_my_retweet: Retweets in Friendica are implemented in a different way
#### Different behaviour
* screen_name: The nick name in friendica is only unique in each network but not for all networks. The users are searched in the following priority: Friendica, StatusNet/GNU Social, Diaspora, pump.io, Twitter. If no contact was found by this way, then the first contact is taken.
* include_entities: Default is "false". If set to "true" then the plain text is formatted so that links are having descriptions.
#### Return values
* cid: Contact id of the user (important for "contact_allow" and "contact_deny")
* network: network of the user
#### 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
* skip_status: Don't show the "status" field. (Default: false)
* include_entities: "true" shows entities for pictures and links (Default: false)
---
### conversation/show (*; AUTH)
Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
#### Parameter
* id: id of the post
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
* include_rts
* trim_user
* contributor_details
---
### direct_messages (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain"
* include_entities: "true" shows entities for pictures and links (Default: false)
* friendica_verbose: "true" enables different error returns (default: "false")
#### Unsupported parameters
* skip_status
---
### direct_messages/all (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain"
* friendica_verbose: "true" enables different error returns (default: "false")
---
### direct_messages/conversation (*; AUTH)
Shows all direct messages of a conversation
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain"
* uri: URI of the conversation
* friendica_verbose: "true" enables different error returns (default: "false")
---
### direct_messages/sent (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain"
* include_entities: "true" shows entities for pictures and links (Default: false)
* friendica_verbose: "true" enables different error returns (default: "false")
---
### direct_messages/new (POST,PUT; AUTH)
#### Parameters
* user_id: id of the user
* screen_name: screen name (for technical reasons, this value is not unique!)
* text: The message
* replyto: ID of the replied direct message
* title: Title of the direct message
---
### direct_messages/destroy (POST,DELETE; AUTH)
#### Parameters
* id: id of the message to be deleted
* include_entities: optional, currently not yet implemented
* friendica_parenturi: optional, can be used for increased safety to delete only intended messages
* friendica_verbose: "true" enables different error returns (default: "false")
#### 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
* profileurl: profile url
---
### favorites (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
* user_id
* screen_name
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
* id
* include_entities: "true" shows entities for pictures and links (Default: false)
---
### favorites/destroy (POST,DELETE; AUTH)
#### Parameters
* id
* include_entities: "true" shows entities for pictures and links (Default: false)
---
### followers/ids (*; AUTH)
#### Parameters
* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
#### Unsupported parameters
* user_id
* screen_name
* cursor
Friendica doesn't allow showing followers of other users.
---
### friends/ids (*; AUTH)
#### Parameters
* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
#### Unsupported parameters
* user_id
* screen_name
* cursor
Friendica doesn't allow showing friends of other users.
---
### help/test (*)
---
### media/upload (POST,PUT; AUTH)
#### Parameters
* media: image data
---
### oauth/request_token (*)
#### Parameters
* oauth_callback
#### Unsupported parameters
* x_auth_access_type
---
### oauth/access_token (*)
#### Parameters
* oauth_verifier
#### Unsupported parameters
* x_auth_password
* x_auth_username
* x_auth_mode
---
### statuses/destroy (POST,DELETE; AUTH)
#### Parameters
* id: message number
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
* trim_user
---
### statuses/followers (*; AUTH)
#### Parameters
* include_entities: "true" shows entities for pictures and links (Default: false)
---
### statuses/friends (*; AUTH)
#### Parameters
* include_entities: "true" shows entities for pictures and links (Default: false)
---
### statuses/friends_timeline (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* exclude_replies: don't show replies (default: false)
* conversation_id: Shows all statuses of a given conversation.
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
* include_rts
* trim_user
* contributor_details
---
### statuses/home_timeline (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* exclude_replies: don't show replies (default: false)
* conversation_id: Shows all statuses of a given conversation.
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
* include_rts
* trim_user
* contributor_details
---
### statuses/mentions (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
* include_rts
* trim_user
* contributor_details
---
### statuses/public_timeline (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* exclude_replies: don't show replies (default: false)
* conversation_id: Shows all statuses of a given conversation.
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
* trim_user
---
### statuses/replies (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
* include_rts
* trim_user
* contributor_details
---
### statuses/retweet (POST,PUT; AUTH)
#### Parameters
* id: message number
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
* trim_user
---
### statuses/show (*; AUTH)
#### Parameters
* id: message number
* conversation: if set to "1" show all messages of the conversation with the given id
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
* include_my_retweet
* trim_user
---
### statuses/update, statuses/update_with_media
#### Parameters
* title: Title of the status
* status: Status in text format
* htmlstatus: Status in HTML format
* in_reply_to_status_id
* lat: latitude
* long: longitude
* media: image data
* source: Application name
* group_allow
* contact_allow
* group_deny
* contact_deny
* network
* include_entities: "true" shows entities for pictures and links (Default: false)
* media_ids: (By now only a single value, no array)
#### Unsupported parameters
* trim_user
* place_id
* display_coordinates
---
### statuses/user_timeline (*; AUTH)
#### Parameters
* user_id: id of the user
* screen_name: screen name (for technical reasons, this value is not unique!)
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* exclude_replies: don't show replies (default: false)
* conversation_id: Shows all statuses of a given conversation.
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
* include_rts
* trim_user
* contributor_details
---
### statusnet/config (*)
---
### statusnet/conversation (*; AUTH)
It shows all direct answers (excluding the original post) to a given id.
#### Parameter
* id: id of the post
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false)
---
### statusnet/version (*)
#### Unsupported parameters
* user_id
* screen_name
* cursor
Friendica doesn't allow showing followers of other users.
---
### users/search (*)
#### Parameters
* q: name of the user
#### Unsupported parameters
* page
* count
* include_entities
---
### users/show (*)
#### Parameters
* user_id: id of the user
* screen_name: screen name (for technical reasons, this value is not unique!)
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
* user_id
* screen_name
* cursor
Friendica doesn't allow showing friends of other users.
---
### account/update_profile_image (POST; AUTH)
#### Parameters
* image: image data as base64 (Twitter has a limit of 700kb, Friendica allows more)
* profile_id (optional): id of the profile for which the image should be used, default is changing the default profile
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",
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
* album: name of the album to be updated
* album_new: new name of the album
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
* photo_id (optional): if specified the photo with this id will be updated
* media (optional): image data as base64, only optional if photo_id is specified (new upload must have media)
* desc (optional): description for the photo, updated when photo_id is specified
* album: name of the album to be deleted (always necessary)
* album_new (optional): can be used to change the album of a single photo if photo_id is specified
* allow_cid/allow_gid/deny_cid/deny_gid (optional): on create: empty string or omitting = public photo, specify in format '```<x><y><z>```' for private photo;
on update: keys need to be present with empty values for setting a private photo now to public
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 way to inform user that updating rights is not the best way, offer a solution to add photo as a new photo with the new rights.
#### 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",
"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
* photo_id: id of the photo to be deleted
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
* id: id of the message to be updated as seen
#### 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
* searchstring: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored)
#### Return values
Returns only tested with JSON, XML might work as well.
On success:
* JSON return {"success":"true","search_results": array of found messages}
* 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
* profile_id: id of the profile to be returned (optional, if omitted all profiles are returned by default)
#### Return values
On success: Array of:
* multi_profiles: true if user has activated multi_profiles
* global_dir: URL of the global directory set in server settings
* friendica_owner: user data of the authenticated user
* profiles: array of the profile data
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)
* statuses/retweets_of_me
* friendships/create
* friendships/destroy
* friendships/exists
* friendships/show
* account/update_profile_background_image
* blocks/create
* blocks/destroy
The following API calls from the Twitter API aren't implemented neither in Friendica nor in GNU Social:
* statuses/mentions_timeline
* statuses/retweets/:id
* statuses/oembed
* statuses/retweeters/ids
* statuses/lookup
* direct_messages/show
* search/tweets
* friendships/no_retweets/ids
* friendships/incoming
* friendships/outgoing
* friendships/update
* friends/list
* friendships/lookup
* account/settings
* account/update_delivery_device
* account/update_profile
* account/update_profile_background_image
* blocks/list
* blocks/ids
* users/lookup
* users/show
* users/search
* account/remove_profile_banner
* account/update_profile_banner
* users/profile_banner
* mutes/users/create
* mutes/users/destroy
* mutes/users/ids
* mutes/users/list
* users/suggestions/:slug
* users/suggestions
* users/suggestions/:slug/members
* favorites/list
* lists/list
* lists/statuses
* lists/members/destroy
* lists/memberships
* lists/subscribers
* lists/subscribers/create
* lists/subscribers/show
* lists/subscribers/destroy
* lists/members/create_all
* lists/members/show
* lists/members
* lists/members/create
* lists/destroy
* lists/update
* lists/create
* lists/show
* lists/subscriptions
* lists/members/destroy_all
* lists/ownerships
* saved_searches/list
* saved_searches/show/:id
* saved_searches/create
* saved_searches/destroy/:id
* geo/id/:place_id
* geo/reverse_geocode
* geo/search
* geo/place
* trends/place
* trends/available
* help/configuration
* help/languages
* help/privacy
* help/tos
* trends/closest
* users/report_spam
---
---
## 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](https://en.wikipedia.org/wiki/CURL) (see [his posting](https://betamax65.de/display/betamax65/43539)).
/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](https://github.com/pafcu/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](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.
