-Friendica API
-===
+# Friendica API
+
+<!-- markdownlint-disable MD010 MD013 MD024 -->
* [Home](help)
## Implemented API calls
### General
+
#### HTTP Method
API endpoints can restrict the method used to request them.
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
* 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 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
+
+* 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:
-```
+
+```json
{
"error": "Specific error message",
"request": "API path requested",
```
xml:
-```
+
+```xml
<status>
<error>Specific error message</error>
<request>API path requested</request>
```
---
+
### 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
* 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: minimum id
* 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: minimum id
* 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: minimum id
* 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: minimum id
* 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
* 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
#### 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: minimum id
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
+
* user_id
* screen_name
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: Send id numbers as text (true) or integers (false)? (default: false)
#### Unsupported parameters
+
* user_id
* screen_name
* cursor
Friendica doesn't allow showing the followers of other users.
---
+
### friends/ids (*; AUTH)
+
#### Parameters
+
* stringify_ids: Send the id numbers as text (true) or integers (false)? (default: false)
#### Unsupported parameters
+
* user_id
* screen_name
* cursor
Friendica doesn't allow showing the friends of other users.
---
+
### help/test (*)
---
+
+### lists/ownerships (*; AUTH)
+
+#### Parameters
+
+* list_id: ID of the list
+* count: Items per page
+* page: Page number
+* since_id: Minimum ID
+* max_id: Maximum ID
+
+#### Unsupported parameters
+
+* slug
+* owner_screen_name
+* owner_id
+* include_entities
+* include_rts
+
+---
+
+### lists/destroy (POST; AUTH)
+
+#### Parameters
+
+* list_id: ID of the list
+
+#### Unsupported parameters
+
+* owner_screen_name
+* owner_id
+* slug
+
+---
+
+### lists/create (POST; AUTH)
+
+#### Parameters
+
+* name: name of the list
+
+#### Unsupported parameters
+
+* mode
+* description
+
+---
+
+### lists/update (POST; AUTH)
+
+#### Parameters
+
+* list_id: ID of the list
+* name: name of the list
+
+#### Unsupported parameters
+
+* slug
+* name
+* mode
+* description
+* owner_screen_name
+* owner_id
+
+---
+
+### lists/statuses (*; AUTH)
+
+#### Parameters
+
+* user_id: ID of the user for whom to return results.
+
+#### Unsupported parameters
+
+* screen_name
+* count
+* cursor
+
+---
+
### 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)
+* count: how many items should be shown (Default: 20)
---
+
### blocks/list (*; AUTH)
#### Parameters
* page: page number
#### Unsupported parameters
+
* cursor
* skip_status
---
+
### statuses/friends_timeline (*; AUTH)
+
#### Parameters
+
* count: Items per page (default: 20)
* page: page number
* since_id: minimum id
* 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: minimum id
* 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: minimum 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: minimum id
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
+
* trim_user
---
+
### statuses/networkpublic_timeline (*; AUTH)
+
#### Parameters
+
* count: Items per page (default: 20)
* page: page number
* since_id: minimum id
* include_entities: "true" shows entities for pictures and links (Default: false)
---
+
### statuses/replies (*; AUTH)
+
#### Parameters
+
* count: Items per page (default: 20)
* page: page number
* since_id: minimum 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
* 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)
* 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
* 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.
---
+
+### search (*; AUTH)
+
+#### Parameters
+
+* q: search query
+* page: the page number (starting at 1) to return
+* rpp: the number of statuses to return per page
+* count: alias for the rpp parameter
+* since_id: returns statuses with ids greater than the given id
+* max_id: returns statuses with ids lower or equal to the given id
+
+#### Unsupported parameters
+
+* geocode
+* lang
+* locale
+* result_type
+* until
+* include_entities
+
+---
+
+### search/tweets (*; AUTH)
+
+This is an alias for `search`.
+
+---
+
+### saved_searches/list (*; AUTH)
+
+This call does not have any parameter.
+
+---
+
### 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.
+---
+
+### users/lookup (*; AUTH)
+
+#### Parameters
+
+* user_id: list of ids to lookup
+
+#### Unsupported parameters
+
+* screen_name
+* include_entities
---
+
### 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
#### 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",
"unable to process image data",
"image upload failed"
+---
-## Implemented API calls (not compatible with other APIs)
+### account/update_profile (POST; AUTH)
+
+#### Parameters
+
+* name (optional): full name of the user
+* description (optional): a description of the user
+
+#### Unsupported parameters
+
+* url
+* location
+* profile_link_color
+* include_entities
+* skip_status
+
+---
+
+### friendships/incoming (*; AUTH)
+
+#### Unsupported parameters
+
+* cursor
+* stringify_ids
+## Implemented API calls (not compatible with other APIs)
---
-### friendica/activity/<verb>
+
+### friendica/activity/[verb]
+
#### parameters
+
* id: item id
Add or remove an activity from an item.
'verb' can be one of:
-- like
-- dislike
-- attendyes
-- attendno
-- attendmaybe
+* like
+* dislike
+* attendyes
+* attendno
+* attendmaybe
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".
#### Return values
On success:
-json
+json:
+
```"ok"```
-xml
+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
+
* gid: optional, if not given, API returns all groups of the user
#### Return values
+
Array of:
* name: name of the group
* gid: id of the group
* user: array of group members (return from api_get_user() function for each member)
-
---
+
### 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
+
* gid: id of the group to be deleted
* name: name of the group to be deleted
#### Return values
+
Array of:
* success: true if successfully deleted
* status: „deleted“ if successfully deleted
* wrong users: empty array
-
---
+
### friendica/group_create (POST,PUT; AUTH)
+
Create the group with the posted array of contacts as members.
#### Parameters
+
* name: name of the group to be created
#### POST data
+
JSON data as Array like the result of "users/group_show":
* gid
* array of users
#### Return values
+
Array of:
* success: true if successfully created or reactivated
* status: „missing user“ | „reactivated“ | „ok“
* wrong users: array of users, which were not available in the contact table
-
---
+
### 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
+
* gid: id of the group to be changed
* name: name of the group to be changed
#### POST data
+
JSON data as array like the result of „users/group_show“:
* gid
* array of users
#### Return values
+
Array of:
* success: true if successfully updated
* status: „missing user“ | „ok“
* wrong users: array of users, which were not available in the contact table
-
-
---
+
### friendica/notifications (GET)
+
Return last 50 notification for current user, ordered by date with unseen item on top
#### Parameters
+
none
#### Return values
+
Array of:
* id: id of the note
* link: link to note
* seen: seen state: 0 or 1
-
---
+
### 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:
-* "success" (json) | <status>success</status>;" (xml)
-
+* `success` (json) | `<status>success</status>` (xml)
---
+
### friendica/photo (*; AUTH)
+
#### Parameters
+
* photo_id: Resource id of a photo.
* scale: (optional) scale value of the photo
#### Return values
-json
-```
+json:
+
+```json
{
"id": "photo id"
"created": "date(YYYY-MM-DD HH:MM:SS)",
}
```
-xml
-```
+xml:
+
+```xml
<photo>
<id>photo id</id>
<created>date(YYYY-MM-DD HH:MM:SS)</created>
```
---
+
### friendica/photos/list (*; AUTH)
Returns a list of all photo resources of the logged in user.
#### Return values
-json
-```
+json:
+
+```json
[
{
id: "resource_id",
]
```
-xml
-```
+xml:
+
+```xml
<photos type="array">
<photo id="resource_id"
album="album name"
```
---
+
### friendica/photoalbum/delete (POST,DELETE; AUTH)
+
#### Parameters
+
* album: name of the album to be deleted
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
#### 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
#### 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 - 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
#### 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}
* 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
+
* 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
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
* 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
* 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/ids
-* users/lookup
* users/show
* users/search
* account/remove_profile_banner
* users/suggestions/:slug/members
* favorites/list
* lists/list
-* lists/statuses
* lists/members/destroy
* lists/memberships
* lists/subscribers
* 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
---
## Usage Examples
+
### BASH / cURL
+```bash
/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 [RSStoFriendika](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.
def tweet(server, message, group_allow=None):
projects / friendica.git / blobdiff