6 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).
8 Please refer to the linked documentation for further information.
10 ## Implemented API calls
15 API endpoints can restrict the method used to request them.
16 Using an invalid method results in HTTP error 405 "Method Not Allowed".
18 In this document, the required method is listed after the endpoint name. "*" means every method can be used.
22 Friendica supports basic http auth and OAuth 1 to authenticate the user to the api.
24 OAuth settings can be added by the user in web UI under /settings/oauth/
26 In this document, endpoints which requires auth are marked with "AUTH" after endpoint name
28 #### Unsupported parameters
29 * cursor: Not implemented in GNU Social
30 * trim_user: Not implemented in GNU Social
31 * contributor_details: Not implemented in GNU Social
32 * place_id: Not implemented in GNU Social
33 * display_coordinates: Not implemented in GNU Social
35 * include_my_retweet: Retweets in Friendica are implemented in a different way
37 #### Different behaviour
38 * 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.
39 * include_entities: Default is "false". If set to "true" then the plain text is formatted so that links are having descriptions.
42 * cid: Contact id of the user (important for "contact_allow" and "contact_deny")
43 * network: network of the user
46 When an error occurs in API call, an HTTP error code is returned, with an error message
48 - 400 Bad Request: if parameters are missing or items can't be found
49 - 403 Forbidden: if the authenticated user is missing
50 - 405 Method Not Allowed: if API was called with an invalid method, eg. GET when API require POST
51 - 501 Not Implemented: if the requested API doesn't exist
52 - 500 Internal Server Error: on other error conditions
59 "error": "Specific error message",
60 "request": "API path requested",
61 "code": "HTTP error code"
68 <error>Specific error message</error>
69 <request>API path requested</request>
70 <code>HTTP error code</code>
75 ### account/rate_limit_status (*; AUTH)
78 ### account/verify_credentials (*; AUTH)
81 * skip_status: Don't show the "status" field. (Default: false)
82 * include_entities: "true" shows entities for pictures and links (Default: false)
85 ### conversation/show (*; AUTH)
86 Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
90 * count: Items per page (default: 20)
92 * since_id: minimum id
94 * include_entities: "true" shows entities for pictures and links (Default: false)
96 #### Unsupported parameters
102 ### direct_messages (*; AUTH)
104 * count: Items per page (default: 20)
106 * since_id: minimum id
108 * getText: Defines the format of the status field. Can be "html" or "plain"
109 * include_entities: "true" shows entities for pictures and links (Default: false)
110 * friendica_verbose: "true" enables different error returns (default: "false")
112 #### Unsupported parameters
116 ### direct_messages/all (*; AUTH)
118 * count: Items per page (default: 20)
120 * since_id: minimum id
122 * getText: Defines the format of the status field. Can be "html" or "plain"
123 * friendica_verbose: "true" enables different error returns (default: "false")
126 ### direct_messages/conversation (*; AUTH)
127 Shows all direct messages of a conversation
129 * count: Items per page (default: 20)
131 * since_id: minimum id
133 * getText: Defines the format of the status field. Can be "html" or "plain"
134 * uri: URI of the conversation
135 * friendica_verbose: "true" enables different error returns (default: "false")
138 ### direct_messages/sent (*; AUTH)
140 * count: Items per page (default: 20)
142 * since_id: minimum id
144 * getText: Defines the format of the status field. Can be "html" or "plain"
145 * include_entities: "true" shows entities for pictures and links (Default: false)
146 * friendica_verbose: "true" enables different error returns (default: "false")
149 ### direct_messages/new (POST,PUT; AUTH)
151 * user_id: id of the user
152 * screen_name: screen name (for technical reasons, this value is not unique!)
154 * replyto: ID of the replied direct message
155 * title: Title of the direct message
158 ### direct_messages/destroy (POST,DELETE; AUTH)
160 * id: id of the message to be deleted
161 * include_entities: optional, currently not yet implemented
162 * friendica_parenturi: optional, can be used for increased safety to delete only intended messages
163 * friendica_verbose: "true" enables different error returns (default: "false")
168 * JSON return as defined for Twitter API not yet implemented
169 * on friendica_verbose=true: JSON return {"result":"ok","message":"message deleted"}
173 * on friendica_verbose=true: different JSON returns {"result":"error","message":"xyz"}
176 ### externalprofile/show (*)
178 * profileurl: profile url
181 ### favorites (*; AUTH)
183 * count: Items per page (default: 20)
185 * since_id: minimum id
187 * include_entities: "true" shows entities for pictures and links (Default: false)
189 #### Unsupported parameters
193 Favorites aren't displayed to other users, so "user_id" and "screen_name" are unsupported.
194 Set this values will result in an empty array.
197 ### favorites/create (POST,PUT; AUTH)
200 * include_entities: "true" shows entities for pictures and links (Default: false)
203 ### favorites/destroy (POST,DELETE; AUTH)
206 * include_entities: "true" shows entities for pictures and links (Default: false)
209 ### followers/ids (*; AUTH)
211 * stringify_ids: Send id numbers as text (true) or integers (false)? (default: false)
213 #### Unsupported parameters
218 Friendica doesn't allow showing the followers of other users.
221 ### friends/ids (*; AUTH)
223 * stringify_ids: Send the id numbers as text (true) or integers (false)? (default: false)
225 #### Unsupported parameters
230 Friendica doesn't allow showing the friends of other users.
236 ### media/upload (POST,PUT; AUTH)
241 ### oauth/request_token (*)
245 #### Unsupported parameters
249 ### oauth/access_token (*)
253 #### Unsupported parameters
259 ### statuses/destroy (POST,DELETE; AUTH)
262 * include_entities: "true" shows entities for pictures and links (Default: false)
264 #### Unsupported parameters
268 ### statuses/followers (*; AUTH)
272 * include_entities: "true" shows entities for pictures and links (Default: false)
275 ### statuses/friends (*; AUTH)
279 * include_entities: "true" shows entities for pictures and links (Default: false)
282 ### blocks/list (*; AUTH)
286 * include_entities: "true" shows entities for pictures and links (Default: false)
287 * count: Items per page (default: 20).
290 #### Unsupported parameters
295 ### statuses/friends_timeline (*; AUTH)
297 * count: Items per page (default: 20)
299 * since_id: minimum id
301 * exclude_replies: don't show replies (default: false)
302 * conversation_id: Shows all statuses of a given conversation.
303 * include_entities: "true" shows entities for pictures and links (Default: false)
305 #### Unsupported parameters
308 * contributor_details
311 ### statuses/home_timeline (*; AUTH)
313 * count: Items per page (default: 20)
315 * since_id: minimum id
317 * exclude_replies: don't show replies (default: false)
318 * conversation_id: Shows all statuses of a given conversation.
319 * include_entities: "true" shows entities for pictures and links (Default: false)
321 #### Unsupported parameters
324 * contributor_details
327 ### statuses/mentions (*; AUTH)
329 * count: Items per page (default: 20)
331 * since_id: minimum id
333 * include_entities: "true" shows entities for pictures and links (Default: false)
335 #### Unsupported parameters
338 * contributor_details
341 ### statuses/public_timeline (*; AUTH)
343 * count: Items per page (default: 20)
345 * since_id: minimum id
347 * exclude_replies: don't show replies (default: false)
348 * conversation_id: Shows all statuses of a given conversation.
349 * include_entities: "true" shows entities for pictures and links (Default: false)
351 #### Unsupported parameters
355 ### statuses/networkpublic_timeline (*; AUTH)
357 * count: Items per page (default: 20)
359 * since_id: minimum id
361 * include_entities: "true" shows entities for pictures and links (Default: false)
364 ### statuses/replies (*; AUTH)
366 * count: Items per page (default: 20)
368 * since_id: minimum id
370 * include_entities: "true" shows entities for pictures and links (Default: false)
372 #### Unsupported parameters
375 * contributor_details
378 ### statuses/retweet (POST,PUT; AUTH)
381 * include_entities: "true" shows entities for pictures and links (Default: false)
383 #### Unsupported parameters
387 ### statuses/show (*; AUTH)
390 * conversation: if set to "1" show all messages of the conversation with the given id
391 * include_entities: "true" shows entities for pictures and links (Default: false)
393 #### Unsupported parameters
398 ### statuses/update, statuses/update_with_media
400 * title: Title of the status
401 * status: Status in text format
402 * htmlstatus: Status in HTML format
403 * in_reply_to_status_id
407 * source: Application name
413 * include_entities: "true" shows entities for pictures and links (Default: false)
414 * media_ids: (By now only a single value, no array)
416 #### Unsupported parameters
419 * display_coordinates
422 ### statuses/user_timeline (*; AUTH)
424 * user_id: id of the user
425 * screen_name: screen name (for technical reasons, this value is not unique!)
426 * count: Items per page (default: 20)
428 * since_id: minimum id
430 * exclude_replies: don't show replies (default: false)
431 * conversation_id: Shows all statuses of a given conversation.
432 * include_entities: "true" shows entities for pictures and links (Default: false)
434 #### Unsupported parameters
438 * contributor_details
441 ### statusnet/config (*)
444 ### statusnet/conversation (*; AUTH)
445 It shows all direct answers (excluding the original post) to a given id.
449 * count: Items per page (default: 20)
451 * since_id: minimum id
453 * include_entities: "true" shows entities for pictures and links (Default: false)
456 ### statusnet/version (*)
458 #### Unsupported parameters
463 Friendica doesn't allow showing followers of other users.
468 * q: name of the user
470 #### Unsupported parameters
478 * user_id: id of the user
479 * screen_name: screen name (for technical reasons, this value is not unique!)
480 * include_entities: "true" shows entities for pictures and links (Default: false)
482 #### Unsupported parameters
487 Friendica doesn't allow showing friends of other users.
491 ### account/update_profile_image (POST; AUTH)
493 * image: image data as base64 (Twitter has a limit of 700kb, Friendica allows more)
494 * profile_id (optional): id of the profile for which the image should be used, default is changing the default profile
496 uploads a new profile image (scales 4-6) to database, changes default or specified profile to the new photo
501 * JSON return: returns the updated user details (see account/verify_credentials)
504 * 403 FORBIDDEN: if not authenticated
505 * 400 BADREQUEST: "no media data submitted", "profile_id not available"
506 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
507 "image size exceeds Friendica Config setting (uploaded size: x)",
508 "unable to process image data",
509 "image upload failed"
512 ## Implemented API calls (not compatible with other APIs)
516 ### friendica/activity/<verb>
520 Add or remove an activity from an item.
521 'verb' can be one of:
529 To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"
530 Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".
531 Attend verbs should be used only with event-related items (there is no check at the moment)
546 ### friendica/group_show (*; AUTH)
547 Return all or a specified group of the user with the containing contacts as array.
550 * gid: optional, if not given, API returns all groups of the user
555 * name: name of the group
556 * gid: id of the group
557 * user: array of group members (return from api_get_user() function for each member)
561 ### friendica/group_delete (POST,DELETE; AUTH)
562 delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted.
565 * gid: id of the group to be deleted
566 * name: name of the group to be deleted
571 * success: true if successfully deleted
572 * gid: gid of the deleted group
573 * name: name of the deleted group
574 * status: „deleted“ if successfully deleted
575 * wrong users: empty array
579 ### friendica/group_create (POST,PUT; AUTH)
580 Create the group with the posted array of contacts as members.
583 * name: name of the group to be created
586 JSON data as Array like the result of "users/group_show":
595 * success: true if successfully created or reactivated
596 * gid: gid of the created group
597 * name: name of the created group
598 * status: „missing user“ | „reactivated“ | „ok“
599 * wrong users: array of users, which were not available in the contact table
603 ### friendica/group_update (POST)
604 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).
607 * gid: id of the group to be changed
608 * name: name of the group to be changed
611 JSON data as array like the result of „users/group_show“:
620 * success: true if successfully updated
621 * gid: gid of the changed group
622 * name: name of the changed group
623 * status: „missing user“ | „ok“
624 * wrong users: array of users, which were not available in the contact table
629 ### friendica/notifications (GET)
630 Return last 50 notification for current user, ordered by date with unseen item on top
639 * type: type of notification as int (see NOTIFY_* constants in boot.php)
640 * name: full name of the contact subject of the note
641 * url: contact's profile url
642 * photo: contact's profile photo
643 * date: datetime string of the note
644 * timestamp: timestamp of the node
645 * date_rel: relative date of the note (eg. "1 hour ago")
646 * msg: note message in bbcode
647 * msg_html: note message in html
648 * msg_plain: note message in plain text
650 * seen: seen state: 0 or 1
654 ### friendica/notifications/seen (POST)
655 Set note as seen, returns item object if possible
658 id: id of the note to set seen
661 If the note is linked to an item, the item is returned, just like one of the "statuses/*_timeline" api.
663 If the note is not linked to an item, a success status is returned:
665 * "success" (json) | <status>success</status>;" (xml)
669 ### friendica/photo (*; AUTH)
671 * photo_id: Resource id of a photo.
672 * scale: (optional) scale value of the photo
674 Returns data of a picture with the given resource.
675 If 'scale' isn't provided, returned data include full url to each scale of the photo.
676 If 'scale' is set, returned data include image data base64 encoded.
678 possibile scale value are:
680 * 0: original or max size by server settings
681 * 1: image with or height at <= 640
682 * 2: image with or height at <= 320
683 * 3: thumbnail 160x160
684 * 4: Profile image at 175x175
685 * 5: Profile image at 80x80
686 * 6: Profile image at 48x48
688 An image used as profile image has only scale 4-6, other images only 0-3
696 "created": "date(YYYY-MM-DD HH:MM:SS)",
697 "edited": "date(YYYY-MM-DD HH:MM:SS)",
698 "title": "photo title",
699 "desc": "photo description",
700 "album": "album name",
701 "filename": "original file name",
705 "profile": "1 if is profile photo",
707 "<scale>": "url to image"
711 "datasize": "size in byte",
712 "data": "base64 encoded image data"
720 <created>date(YYYY-MM-DD HH:MM:SS)</created>
721 <edited>date(YYYY-MM-DD HH:MM:SS)</edited>
722 <title>photo title</title>
723 <desc>photo description</desc>
724 <album>album name</album>
725 <filename>original file name</filename>
726 <type>mime type</type>
727 <height>number</height>
728 <width>number</width>
729 <profile>1 if is profile photo</profile>
731 <link type="mime type" scale="scale number" href="image url"/>
738 ### friendica/photos/list (*; AUTH)
740 Returns a list of all photo resources of the logged in user.
750 filename: "original file name",
751 type: "image mime type",
752 thumb: "url to thumb sized image"
760 <photos type="array">
761 <photo id="resource_id"
763 filename="original file name"
764 type="image mime type">
765 "url to thumb sized image"
772 ### friendica/photoalbum/delete (POST,DELETE; AUTH)
774 * album: name of the album to be deleted
776 deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this
781 * JSON return {"result":"deleted","message":"album 'xyz' with all containing photos has been deleted."}
784 * 403 FORBIDDEN: if not authenticated
785 * 400 BADREQUEST: "no albumname specified", "album not available"
786 * 500 INTERNALSERVERERROR: "problem with deleting item occured", "unknown error - deleting from database failed"
790 ### friendica/photoalbum/update (POST,PUT; AUTH)
792 * album: name of the album to be updated
793 * album_new: new name of the album
795 changes the album name to album_new for all photos in album
800 * JSON return {"result":"updated","message":"album 'abc' with all containing photos has been renamed to 'xyz'."}
803 * 403 FORBIDDEN: if not authenticated
804 * 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available"
805 * 500 INTERNALSERVERERROR: "unknown error - updating in database failed"
809 ### friendica/photo/create (POST; AUTH)
810 ### friendica/photo/update (POST; AUTH)
812 * photo_id (optional): if specified the photo with this id will be updated
813 * media (optional): image data as base64, only optional if photo_id is specified (new upload must have media)
814 * desc (optional): description for the photo, updated when photo_id is specified
815 * album: name of the album to be deleted (always necessary)
816 * album_new (optional): can be used to change the album of a single photo if photo_id is specified
817 * 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;
818 on update: keys need to be present with empty values for changing a private photo to public
820 both calls point to one function for creating AND updating photos.
821 Saves data for the scales 0-2 to database (see above for scale description).
822 Call adds non-visible entries to items table to enable authenticated contacts to comment/like the photo.
823 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.
824 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.
829 * new photo uploaded: JSON return with photo data (see friendica/photo)
830 * photo updated - changed photo data: JSON return with photo data (see friendica/photo)
831 * photo updated - changed info: JSON return {"result":"updated","message":"Image id 'xyz' has been updated."}
832 * photo updated - nothing changed: JSON return {"result":"cancelled","message":"Nothing to update for image id 'xyz'."}
835 * 403 FORBIDDEN: if not authenticated
836 * 400 BADREQUEST: "no albumname specified", "no media data submitted", "photo not available", "acl data invalid"
837 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
838 "image size exceeds Friendica Config setting (uploaded size: x)",
839 "unable to process image data",
840 "image upload failed",
841 "unknown error - uploading photo failed, see Friendica log for more information",
842 "unknown error - update photo entry in database failed",
843 "unknown error - this error on uploading or updating a photo should never happen"
847 ### friendica/photo/delete (DELETE; AUTH)
849 * photo_id: id of the photo to be deleted
851 deletes a single image with the specified id, is not reversible -> ensure that client is asking user for being sure to do this
852 Sets item table entries for this photo to deleted = 1
857 * JSON return {"result":"deleted","message":"photo with id 'xyz' has been deleted from server."}
860 * 403 FORBIDDEN: if not authenticated
861 * 400 BADREQUEST: "no photo_id specified", "photo not available"
862 * 500 INTERNALSERVERERROR: "unknown error on deleting photo", "problem with deleting items occurred"
866 ### friendica/direct_messages_setseen (GET; AUTH)
868 * id: id of the message to be updated as seen
873 * JSON return {"result":"ok","message":"message set to seen"}
876 * different JSON returns {"result":"error","message":"xyz"}
879 ### friendica/direct_messages_search (GET; AUTH)
881 * searchstring: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored)
884 Returns only tested with JSON, XML might work as well.
887 * JSON return {"success":"true","search_results": array of found messages}
888 * JSOn return {"success":"false","search_results":"nothing found"}
891 * different JSON returns {"result":"error","message":"searchstring not specified"}
894 ### friendica/profile/show (GET; AUTH)
895 show data of all profiles or a single profile of the authenticated user
898 * profile_id: id of the profile to be returned (optional, if omitted all profiles are returned by default)
901 On success: Array of:
903 * multi_profiles: true if user has activated multi_profiles
904 * global_dir: URL of the global directory set in server settings
905 * friendica_owner: user data of the authenticated user
906 * profiles: array of the profile data
909 HTTP 403 Forbidden: when no authentication was provided
910 HTTP 400 Bad Request: if given profile_id is not in the database or is not assigned to the authenticated user
912 General description of profile data in API returns:
915 * is_default: true if this is the public profile
916 * hide_friends: true if friends are hidden
919 * publish: true if published on the server's local directory
920 * net_publish: true if published to global_dir
921 * description ... homepage: different data fields from 'profile' table in database
922 * users: array with the users allowed to view this profile (empty if is_default=true)
926 ## Not Implemented API calls
927 The following API calls are implemented in GNU Social but not in Friendica: (incomplete)
929 * statuses/retweets_of_me
931 * friendships/destroy
934 * account/update_profile_background_image
938 The following API calls from the Twitter API are not implemented in either Friendica or GNU Social:
940 * statuses/mentions_timeline
941 * statuses/retweets/:id
943 * statuses/retweeters/ids
945 * direct_messages/show
947 * friendships/no_retweets/ids
948 * friendships/incoming
949 * friendships/outgoing
954 * account/update_delivery_device
955 * account/update_profile
956 * account/update_profile_background_image
961 * account/remove_profile_banner
962 * account/update_profile_banner
963 * users/profile_banner
965 * mutes/users/destroy
968 * users/suggestions/:slug
970 * users/suggestions/:slug/members
974 * lists/members/destroy
977 * lists/subscribers/create
978 * lists/subscribers/show
979 * lists/subscribers/destroy
980 * lists/members/create_all
983 * lists/members/create
988 * lists/subscriptions
989 * lists/members/destroy_all
991 * saved_searches/list
992 * saved_searches/show/:id
993 * saved_searches/create
994 * saved_searches/destroy/:id
996 * geo/reverse_geocode
1001 * help/configuration
1015 /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"
1018 The [RSStoFriedika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python.
1019 The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.
1021 def tweet(server, message, group_allow=None):
1022 url = server + '/api/statuses/update'
1023 urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))
1025 There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.