-Friendica API\r
-===\r
-\r
-* [Home](help)\r
-\r
-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).\r
-\r
-Please refer to the linked documentation for further information.\r
-\r
-## Implemented API calls\r
-\r
-### General\r
-#### HTTP Method\r
-\r
-API endpoints can restrict the method used to request them.\r
-Using an invalid method results in HTTP error 405 "Method Not Allowed".\r
-\r
-In this document, the required method is listed after the endpoint name. "*" means every method can be used.\r
-\r
-#### Auth\r
-\r
-Friendica supports basic http auth and OAuth 1 to authenticate the user to the api.\r
-\r
-OAuth settings can be added by the user in web UI under /settings/oauth/\r
-\r
-In this document, endpoints which requires auth are marked with "AUTH" after endpoint name\r
-\r
-#### Unsupported parameters\r
-* cursor: Not implemented in GNU Social\r
-* trim_user: Not implemented in GNU Social\r
-* contributor_details: Not implemented in GNU Social\r
-* place_id: Not implemented in GNU Social\r
-* display_coordinates: Not implemented in GNU Social\r
-* include_rts: To-Do\r
-* include_my_retweet: Retweets in Friendica are implemented in a different way\r
-\r
-#### Different behaviour\r
-* 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.\r
-* include_entities: Default is "false". If set to "true" then the plain text is formatted so that links are having descriptions.\r
-\r
-#### Return values\r
-* cid: Contact id of the user (important for "contact_allow" and "contact_deny")\r
-* network: network of the user\r
-\r
-#### Errors\r
-When an error occour in API call, an HTTP error code is returned, with an error message\r
-Usually:\r
-- 400 Bad Request: if parameter are missing or items can't be found\r
-- 403 Forbidden: if authenticated user is missing\r
-- 405 Method Not Allowed: if API was called with invalid method, eg. GET when API require POST\r
-- 501 Not Implemented: if requested API doesn't exists\r
-- 500 Internal Server Error: on other error contitions\r
-\r
-Error body is\r
-\r
-json:\r
-```\r
- {\r
- "error": "Specific error message",\r
- "request": "API path requested",\r
- "code": "HTTP error code"\r
- }\r
-```\r
-\r
-xml:\r
-```\r
- <status>\r
- <error>Specific error message</error>\r
- <request>API path requested</request>\r
- <code>HTTP error code</code>\r
- </status>\r
-```\r
-\r
----\r
-### account/rate_limit_status (*; AUTH)\r
-\r
----\r
-### account/verify_credentials (*; AUTH)\r
-#### Parameters\r
-\r
-* skip_status: Don't show the "status" field. (Default: false)\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
----\r
-### conversation/show (*; AUTH)\r
-Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.\r
-\r
-#### Parameter\r
-* id: id of the post\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-#### Unsupported parameters\r
-* include_rts\r
-* trim_user\r
-* contributor_details\r
-\r
----\r
-### direct_messages (*; AUTH)\r
-#### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* getText: Defines the format of the status field. Can be "html" or "plain"\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-* friendica_verbose: "true" enables different error returns (default: "false")\r
-\r
-#### Unsupported parameters\r
-* skip_status\r
-\r
----\r
-### direct_messages/all (*; AUTH)\r
-#### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* getText: Defines the format of the status field. Can be "html" or "plain"\r
-* friendica_verbose: "true" enables different error returns (default: "false")\r
-\r
----\r
-### direct_messages/conversation (*; AUTH)\r
-Shows all direct messages of a conversation\r
-#### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* getText: Defines the format of the status field. Can be "html" or "plain"\r
-* uri: URI of the conversation\r
-* friendica_verbose: "true" enables different error returns (default: "false")\r
-\r
----\r
-### direct_messages/sent (*; AUTH)\r
-#### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* getText: Defines the format of the status field. Can be "html" or "plain"\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-* friendica_verbose: "true" enables different error returns (default: "false")\r
-\r
----\r
-### direct_messages/new (POST,PUT; AUTH)\r
-#### Parameters\r
-* user_id: id of the user\r
-* screen_name: screen name (for technical reasons, this value is not unique!)\r
-* text: The message\r
-* replyto: ID of the replied direct message\r
-* title: Title of the direct message\r
-\r
----\r
-### direct_messages/destroy (POST,DELETE; AUTH)\r
-#### Parameters\r
-* id: id of the message to be deleted\r
-* include_entities: optional, currently not yet implemented\r
-* friendica_parenturi: optional, can be used for increased safety to delete only intended messages\r
-* friendica_verbose: "true" enables different error returns (default: "false")\r
-\r
-#### Return values\r
-\r
-On success:\r
-* JSON return as defined for Twitter API not yet implemented\r
-* on friendica_verbose=true: JSON return {"result":"ok","message":"message deleted"}\r
-\r
-On error:\r
-HTTP 400 BadRequest\r
-* on friendica_verbose=true: different JSON returns {"result":"error","message":"xyz"}\r
-\r
----\r
-### favorites (*; AUTH)\r
-#### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-#### Unsupported parameters\r
-* user_id\r
-* screen_name\r
-\r
-Favorites aren't displayed to other users, so "user_id" and "screen_name" are unsupported.\r
-Set this values will result in an empty array.\r
-\r
----\r
-### favorites/create (POST,PUT; AUTH)\r
-#### Parameters\r
-* id\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
----\r
-### favorites/destroy (POST,DELETE; AUTH)\r
-#### Parameters\r
-* id\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
----\r
-### followers/ids (*; AUTH)\r
-#### Parameters\r
-* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)\r
-\r
-#### Unsupported parameters\r
-* user_id\r
-* screen_name\r
-* cursor\r
-\r
-Friendica doesn't allow showing followers of other users.\r
-\r
----\r
-### friends/ids (*; AUTH)\r
-#### Parameters\r
-* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)\r
-\r
-#### Unsupported parameters\r
-* user_id\r
-* screen_name\r
-* cursor\r
-\r
-Friendica doesn't allow showing friends of other users.\r
-\r
----\r
-### help/test (*)\r
-\r
----\r
-### media/upload (POST,PUT; AUTH)\r
-#### Parameters\r
-* media: image data\r
-\r
----\r
-### oauth/request_token (*)\r
-#### Parameters\r
-* oauth_callback\r
-\r
-#### Unsupported parameters\r
-* x_auth_access_type\r
-\r
----\r
-### oauth/access_token (*)\r
-#### Parameters\r
-* oauth_verifier\r
-\r
-#### Unsupported parameters\r
-* x_auth_password\r
-* x_auth_username\r
-* x_auth_mode\r
-\r
----\r
-### statuses/destroy (POST,DELETE; AUTH)\r
-#### Parameters\r
-* id: message number\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-#### Unsupported parameters\r
-* trim_user\r
-\r
----\r
-### statuses/followers (*; AUTH)\r
-\r
-#### Parameters\r
-\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
----\r
-### statuses/friends (*; AUTH)\r
-\r
-#### Parameters\r
-\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
----\r
-### statuses/friends_timeline (*; AUTH)\r
-#### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* exclude_replies: don't show replies (default: false)\r
-* conversation_id: Shows all statuses of a given conversation.\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-#### Unsupported parameters\r
-* include_rts\r
-* trim_user\r
-* contributor_details\r
-\r
----\r
-### statuses/home_timeline (*; AUTH)\r
-#### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* exclude_replies: don't show replies (default: false)\r
-* conversation_id: Shows all statuses of a given conversation.\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-#### Unsupported parameters\r
-* include_rts\r
-* trim_user\r
-* contributor_details\r
-\r
----\r
-### statuses/mentions (*; AUTH)\r
-#### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-#### Unsupported parameters\r
-* include_rts\r
-* trim_user\r
-* contributor_details\r
-\r
----\r
-### statuses/public_timeline (*; AUTH)\r
-#### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* exclude_replies: don't show replies (default: false)\r
-* conversation_id: Shows all statuses of a given conversation.\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-#### Unsupported parameters\r
-* trim_user\r
-\r
----\r
-### statuses/replies (*; AUTH)\r
-#### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-#### Unsupported parameters\r
-* include_rts\r
-* trim_user\r
-* contributor_details\r
-\r
----\r
-### statuses/retweet (POST,PUT; AUTH)\r
-#### Parameters\r
-* id: message number\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-#### Unsupported parameters\r
-* trim_user\r
-\r
----\r
-### statuses/show (*; AUTH)\r
-#### Parameters\r
-* id: message number\r
-* conversation: if set to "1" show all messages of the conversation with the given id\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-#### Unsupported parameters\r
-* include_my_retweet\r
-* trim_user\r
-\r
----\r
-### statuses/update, statuses/update_with_media\r
-#### Parameters\r
-* title: Title of the status\r
-* status: Status in text format\r
-* htmlstatus: Status in HTML format\r
-* in_reply_to_status_id\r
-* lat: latitude\r
-* long: longitude\r
-* media: image data\r
-* source: Application name\r
-* group_allow\r
-* contact_allow\r
-* group_deny\r
-* contact_deny\r
-* network\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-* media_ids: (By now only a single value, no array)\r
-\r
-#### Unsupported parameters\r
-* trim_user\r
-* place_id\r
-* display_coordinates\r
-\r
----\r
-### statuses/user_timeline (*; AUTH)\r
-#### Parameters\r
-* user_id: id of the user\r
-* screen_name: screen name (for technical reasons, this value is not unique!)\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* exclude_replies: don't show replies (default: false)\r
-* conversation_id: Shows all statuses of a given conversation.\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-#### Unsupported parameters\r
-\r
-* include_rts\r
-* trim_user\r
-* contributor_details\r
-\r
----\r
-### statusnet/config (*)\r
-\r
----\r
-### statusnet/conversation (*; AUTH)\r
-It shows all direct answers (excluding the original post) to a given id.\r
-\r
-#### Parameter\r
-* id: id of the post\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
----\r
-### statusnet/version (*)\r
-\r
-#### Unsupported parameters\r
-* user_id\r
-* screen_name\r
-* cursor\r
-\r
-Friendica doesn't allow showing followers of other users.\r
-\r
----\r
-### users/search (*)\r
-#### Parameters\r
-* q: name of the user\r
-\r
-#### Unsupported parameters\r
-* page\r
-* count\r
-* include_entities\r
-\r
----\r
-### users/show (*)\r
-#### Parameters\r
-* user_id: id of the user\r
-* screen_name: screen name (for technical reasons, this value is not unique!)\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-#### Unsupported parameters\r
-* user_id\r
-* screen_name\r
-* cursor\r
-\r
-Friendica doesn't allow showing friends of other users.\r
-\r
-\r
-## Implemented API calls (not compatible with other APIs)\r
-\r
-\r
----\r
-### friendica/activity/<verb>\r
-#### parameters\r
-* id: item id\r
-\r
-Add or remove an activity from an item.\r
-'verb' can be one of:\r
-\r
-- like\r
-- dislike\r
-- attendyes\r
-- attendno\r
-- attendmaybe\r
-\r
-To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"\r
-Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".\r
-Attend verbs should be used only with event-related items (there is no check at the moment)\r
-\r
-#### Return values\r
-\r
-On success:\r
-json\r
-```"ok"```\r
-\r
-xml\r
-```<ok>true</ok>```\r
-\r
-On error:\r
-HTTP 400 BadRequest\r
-\r
----\r
-### friendica/group_show (*; AUTH)\r
-Return all or a specified group of the user with the containing contacts as array.\r
-\r
-#### Parameters\r
-* gid: optional, if not given, API returns all groups of the user\r
-\r
-#### Return values\r
-Array of:\r
-\r
-* name: name of the group\r
-* gid: id of the group\r
-* user: array of group members (return from api_get_user() function for each member)\r
-\r
-\r
----\r
-### friendica/group_delete (POST,DELETE; AUTH)\r
-delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted.\r
-\r
-#### Parameters\r
-* gid: id of the group to be deleted\r
-* name: name of the group to be deleted\r
-\r
-#### Return values\r
-Array of:\r
-\r
-* success: true if successfully deleted\r
-* gid: gid of the deleted group\r
-* name: name of the deleted group\r
-* status: „deleted“ if successfully deleted\r
-* wrong users: empty array\r
-\r
-\r
----\r
-### friendica/group_create (POST,PUT; AUTH)\r
-Create the group with the posted array of contacts as members.\r
-\r
-#### Parameters\r
-* name: name of the group to be created\r
-\r
-#### POST data\r
-JSON data as Array like the result of "users/group_show":\r
-\r
-* gid\r
-* name\r
-* array of users\r
-\r
-#### Return values\r
-Array of:\r
-\r
-* success: true if successfully created or reactivated\r
-* gid: gid of the created group\r
-* name: name of the created group\r
-* status: „missing user“ | „reactivated“ | „ok“\r
-* wrong users: array of users, which were not available in the contact table\r
-\r
-\r
----\r
-### friendica/group_update (POST)\r
-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).\r
-\r
-#### Parameters\r
-* gid: id of the group to be changed\r
-* name: name of the group to be changed\r
-\r
-#### POST data\r
-JSON data as array like the result of „users/group_show“:\r
-\r
-* gid\r
-* name\r
-* array of users\r
-\r
-#### Return values\r
-Array of:\r
-\r
-* success: true if successfully updated\r
-* gid: gid of the changed group\r
-* name: name of the changed group\r
-* status: „missing user“ | „ok“\r
-* wrong users: array of users, which were not available in the contact table\r
-\r
-\r
-\r
----\r
-### friendica/notifications (GET)\r
-Return last 50 notification for current user, ordered by date with unseen item on top\r
-\r
-#### Parameters\r
-none\r
-\r
-#### Return values\r
-Array of:\r
-\r
-* id: id of the note\r
-* type: type of notification as int (see NOTIFY_* constants in boot.php)\r
-* name: full name of the contact subject of the note\r
-* url: contact's profile url\r
-* photo: contact's profile photo\r
-* date: datetime string of the note\r
-* timestamp: timestamp of the node\r
-* date_rel: relative date of the note (eg. "1 hour ago")\r
-* msg: note message in bbcode\r
-* msg_html: note message in html\r
-* msg_plain: note message in plain text\r
-* link: link to note\r
-* seen: seen state: 0 or 1\r
-\r
-\r
----\r
-### friendica/notifications/seen (POST)\r
-Set note as seen, returns item object if possible\r
-\r
-#### Parameters\r
-id: id of the note to set seen\r
-\r
-#### Return values\r
-If the note is linked to an item, the item is returned, just like one of the "statuses/*_timeline" api.\r
-\r
-If the note is not linked to an item, a success status is returned:\r
-\r
-* "success" (json) | "<status>success</status>" (xml)\r
-\r
-\r
----\r
-### friendica/photo (*; AUTH)\r
-#### Parameters\r
-* photo_id: Resource id of a photo.\r
-* scale: (optional) scale value of the photo\r
-\r
-Returns data of a picture with the given resource.\r
-If 'scale' isn't provided, returned data include full url to each scale of the photo.\r
-If 'scale' is set, returned data include image data base64 encoded.\r
-\r
-possibile scale value are:\r
-\r
-* 0: original or max size by server settings\r
-* 1: image with or height at <= 640\r
-* 2: image with or height at <= 320\r
-* 3: thumbnail 160x160\r
-* 4: Profile image at 175x175\r
-* 5: Profile image at 80x80\r
-* 6: Profile image at 48x48\r
-\r
-An image used as profile image has only scale 4-6, other images only 0-3\r
-\r
-#### Return values\r
-\r
-json\r
-```\r
- {\r
- "id": "photo id"\r
- "created": "date(YYYY-MM-GG HH:MM:SS)",\r
- "edited": "date(YYYY-MM-GG HH:MM:SS)",\r
- "title": "photo title",\r
- "desc": "photo description",\r
- "album": "album name",\r
- "filename": "original file name",\r
- "type": "mime type",\r
- "height": "number",\r
- "width": "number",\r
- "profile": "1 if is profile photo",\r
- "link": {\r
- "<scale>": "url to image"\r
- ...\r
- },\r
- // if 'scale' is set\r
- "datasize": "size in byte",\r
- "data": "base64 encoded image data"\r
- }\r
-```\r
-\r
-xml\r
-```\r
- <photo>\r
- <id>photo id</id>\r
- <created>date(YYYY-MM-GG HH:MM:SS)</created>\r
- <edited>date(YYYY-MM-GG HH:MM:SS)</edited>\r
- <title>photo title</title>\r
- <desc>photo description</desc>\r
- <album>album name</album>\r
- <filename>original file name</filename>\r
- <type>mime type</type>\r
- <height>number</height>\r
- <width>number</width>\r
- <profile>1 if is profile photo</profile>\r
- <links type="array">\r
- <link type="mime type" scale="scale number" href="image url"/>\r
- ...\r
- </links>\r
- </photo>\r
-```\r
-\r
----\r
-### friendica/photos/list (*; AUTH)\r
-\r
-Returns a list of all photo resources of the logged in user.\r
-\r
-#### Return values\r
-\r
-json\r
-```\r
- [\r
- {\r
- id: "resource_id",\r
- album: "album name",\r
- filename: "original file name",\r
- type: "image mime type",\r
- thumb: "url to thumb sized image"\r
- },\r
- ...\r
- ]\r
-```\r
-\r
-xml\r
-```\r
- <photos type="array">\r
- <photo id="resource_id"\r
- album="album name"\r
- filename="original file name"\r
- type="image mime type">\r
- "url to thumb sized image"\r
- </photo>\r
- ...\r
- </photos>\r
-```\r
-\r
----\r
-### friendica/direct_messages_setseen (GET; AUTH)\r
-#### Parameters\r
-* id: id of the message to be updated as seen\r
-\r
-#### Return values\r
-\r
-On success:\r
-* JSON return {"result":"ok","message":"message set to seen"}\r
-\r
-On error:\r
-* different JSON returns {"result":"error","message":"xyz"}\r
-\r
----\r
-### friendica/direct_messages_search (GET; AUTH)\r
-#### Parameters\r
-* searchstring: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored)\r
-\r
-#### Return values\r
-Returns only tested with JSON, XML might work as well.\r
-\r
-On success:\r
-* JSON return {"success":"true","search_results": array of found messages}\r
-* JSOn return {"success":"false","search_results":"nothing found"}\r
-\r
-On error:\r
-* different JSON returns {"result":"error","message":"searchstring not specified"}\r
-\r
----\r
-### friendica/profile/show (GET; AUTH)\r
-show data of all profiles or a single profile of the authenticated user\r
-\r
-#### Parameters\r
-* profile_id: id of the profile to be returned (optional, if omitted all profiles are returned by default)\r
-\r
-#### Return values\r
-On success: Array of:\r
-\r
-* multi_profiles: true if user has activated multi_profiles\r
-* global_dir: URL of the global directory set in server settings\r
-* friendica_owner: user data of the authenticated user\r
-* profiles: array of the profile data\r
-\r
-On error: \r
-HTTP 403 Forbidden: when no authentication provided\r
-HTTP 400 Bad Request: if given profile_id is not in db or not assigned to authenticated user\r
-\r
-General description of profile data in API returns:\r
-* profile_id\r
-* profile_name\r
-* is_default: true if this is the public profile\r
-* hide_friends: true if friends are hidden\r
-* profile_photo\r
-* profile_thumb\r
-* publish: true if published on the server's local directory\r
-* net_publish: true if published to global_dir\r
-* description ... homepage: different data fields from 'profile' table in database\r
-* users: array with the users allowed to view this profile (empty if is_default=true)\r
-\r
-\r
----\r
-## Not Implemented API calls\r
-The following API calls are implemented in GNU Social but not in Friendica: (incomplete)\r
-\r
-* statuses/retweets_of_me\r
-* friendships/create\r
-* friendships/destroy\r
-* friendships/exists\r
-* friendships/show\r
-* account/update_profile_background_image\r
-* account/update_profile_image\r
-* blocks/create\r
-* blocks/destroy\r
-\r
-The following API calls from the Twitter API aren't implemented neither in Friendica nor in GNU Social:\r
-\r
-* statuses/mentions_timeline\r
-* statuses/retweets/:id\r
-* statuses/oembed\r
-* statuses/retweeters/ids\r
-* statuses/lookup\r
-* direct_messages/show\r
-* search/tweets\r
-* friendships/no_retweets/ids\r
-* friendships/incoming\r
-* friendships/outgoing\r
-* friendships/update\r
-* friends/list\r
-* friendships/lookup\r
-* account/settings\r
-* account/update_delivery_device\r
-* account/update_profile\r
-* account/update_profile_background_image\r
-* account/update_profile_image\r
-* blocks/list\r
-* blocks/ids\r
-* users/lookup\r
-* users/show\r
-* users/search\r
-* account/remove_profile_banner\r
-* account/update_profile_banner\r
-* users/profile_banner\r
-* mutes/users/create\r
-* mutes/users/destroy\r
-* mutes/users/ids\r
-* mutes/users/list\r
-* users/suggestions/:slug\r
-* users/suggestions\r
-* users/suggestions/:slug/members\r
-* favorites/list\r
-* lists/list\r
-* lists/statuses\r
-* lists/members/destroy\r
-* lists/memberships\r
-* lists/subscribers\r
-* lists/subscribers/create\r
-* lists/subscribers/show\r
-* lists/subscribers/destroy\r
-* lists/members/create_all\r
-* lists/members/show\r
-* lists/members\r
-* lists/members/create\r
-* lists/destroy\r
-* lists/update\r
-* lists/create\r
-* lists/show\r
-* lists/subscriptions\r
-* lists/members/destroy_all\r
-* lists/ownerships\r
-* saved_searches/list\r
-* saved_searches/show/:id\r
-* saved_searches/create\r
-* saved_searches/destroy/:id\r
-* geo/id/:place_id\r
-* geo/reverse_geocode\r
-* geo/search\r
-* geo/place\r
-* trends/place\r
-* trends/available\r
-* help/configuration\r
-* help/languages\r
-* help/privacy\r
-* help/tos\r
-* trends/closest\r
-* users/report_spam\r
-\r
----\r
-\r
----\r
-\r
-## Usage Examples\r
-### BASH / cURL\r
-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)).\r
-\r
-/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"\r
-\r
-### Python\r
-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.\r
-\r
-def tweet(server, message, group_allow=None):\r
-url = server + '/api/statuses/update'\r
-urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))\r
-\r
-There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.\r
+# Friendica API
+
+<!-- markdownlint-disable MD010 MD013 MD024 -->
+
+* [Home](help)
+
+The Friendica API aims to be compatible with 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 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:
+
+```json
+ {
+ "error": "Specific error message",
+ "request": "API path requested",
+ "code": "HTTP error code"
+ }
+```
+
+xml:
+
+```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: minimum 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: minimum 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: minimum 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: minimum 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: minimum 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: minimum 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: 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
+
+* include_entities: "true" shows entities for pictures and links (Default: false)
+* count: Items per page (default: 20).
+* 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
+* 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: minimum 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: minimum 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: minimum 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/networkpublic_timeline (*; AUTH)
+
+#### Parameters
+
+* count: Items per page (default: 20)
+* page: page number
+* since_id: minimum id
+* max_id: maximum 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
+* 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: minimum 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: minimum 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.
+
+---
+
+### 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
+
+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"
+
+---
+
+### 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]
+
+#### parameters
+
+* id: item id
+
+Add or remove an activity from an item.
+'verb' can be one of:
+
+* 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".
+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
+
+* 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
+* gid: gid of the deleted group
+* name: name of the deleted group
+* 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
+* name
+* array of users
+
+#### Return values
+
+Array of:
+
+* success: true if successfully created or reactivated
+* gid: gid of the created group
+* name: name of the created group
+* 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
+* name
+* array of users
+
+#### Return values
+
+Array of:
+
+* success: true if successfully updated
+* gid: gid of the changed group
+* name: name of the changed group
+* 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
+* type: type of notification as int (see NOTIFY_* constants in boot.php)
+* name: full name of the contact subject of the note
+* url: contact's profile url
+* photo: contact's profile photo
+* date: datetime string of the note
+* timestamp: timestamp of the node
+* date_rel: relative date of the note (eg. "1 hour ago")
+* msg: note message in bbcode
+* msg_html: note message in html
+* msg_plain: note message in plain text
+* 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)
+
+---
+
+### friendica/photo (*; AUTH)
+
+#### Parameters
+
+* photo_id: Resource id of a photo.
+* scale: (optional) scale value of the photo
+
+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:
+
+* 0: original or max size by server settings
+* 1: image with or height at <= 640
+* 2: image with or height at <= 320
+* 3: thumbnail 160x160
+* 4: Profile image at 175x175
+* 5: Profile image at 80x80
+* 6: Profile image at 48x48
+
+An image used as profile image has only scale 4-6, other images only 0-3
+
+#### Return values
+
+json:
+
+```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:
+
+```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:
+
+```json
+ [
+ {
+ id: "resource_id",
+ album: "album name",
+ filename: "original file name",
+ type: "image mime type",
+ thumb: "url to thumb sized image"
+ },
+ ...
+ ]
+```
+
+xml:
+
+```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
+
+* 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
+
+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 changing a private photo 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 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
+
+* 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}
+* 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
+* 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 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)
+
+* 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 are not implemented in either Friendica or GNU Social:
+
+* statuses/mentions_timeline
+* statuses/retweets/:id
+* statuses/oembed
+* statuses/retweeters/ids
+* statuses/lookup
+* direct_messages/show
+* friendships/no_retweets/ids
+* friendships/outgoing
+* friendships/update
+* friends/list
+* friendships/lookup
+* account/settings
+* account/update_delivery_device
+* blocks/ids
+* 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/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/show
+* lists/subscriptions
+* lists/members/destroy_all
+* 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
+
+```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 [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):
+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](https://bitbucket.org/tobiasd/python-friendica) for using the API.
projects / friendica.git / blobdiff