4 * [Using the APIs](help/api)
8 Friendica provides the following specific endpoints.
10 Authentication is the same as described in [Using the APIs](help/api#Authentication).
14 These endpoints uses the [Friendica API entities](help/API-Entities).
18 ### GET api/friendica/events
20 Returns a list of [Event](help/API-Entities#Event) entities for the current logged in user.
24 - `since_id`: (optional) minimum event id for pagination
25 - `count`: maximum number of items returned, default 20
27 ### POST api/friendica/event_create
29 Create a new event for the current logged in user.
33 - `id` : (optional) id of event, event will be amended if supplied
34 - `name` : name of the event (required)
35 - `start_time` : start of the event (ISO), required
36 - `end_time` : (optional) end of the event, event is open end, if not supplied
37 - `desc` : (optional) description of the event
38 - `place` : (optional) location of the event
39 - `publish` : (optional) create message for event
40 - `allow_cid` : (optional) ACL-formatted list of allowed contact ids if private event
41 - `allow_gid` : (optional) ACL-formatted list of disallowed contact ids if private event
42 - `deny_cid` : (optional) ACL-formatted list of allowed circle ids if private event
43 - `deny_gid` : (optional) ACL-formatted list of disallowed circle ids if private event
45 ### POST api/friendica/event_delete
47 Delete event from calendar (not the message)
51 - `id` : id of event to be deleted
53 ### GET api/externalprofile/show
55 Returns a [Contact](help/API-Entities#Contact) entity for the provided profile URL.
59 - `profileurl`: Profile URL
61 ### GET api/statuses/public_timeline
63 Returns a list of public [Items](help/API-Entities#Item) posted on this node.
64 Equivalent of the local community page.
68 * `count`: Items per page (default: 20)
70 * `since_id`: minimum id
71 * `max_id`: maximum id
72 * `exclude_replies`: don't show replies (default: false)
73 * `conversation_id`: Shows all statuses of a given conversation.
74 * `include_entities`: "true" shows entities for pictures and links (Default: false)
76 #### Unsupported parameters
80 ### GET api/statuses/networkpublic_timeline
82 Returns a list of public [Items](help/API-Entities#Item) this node is aware of.
83 Equivalent of the global community page.
87 * `count`: Items per page (default: 20)
89 * `since_id`: minimum id
90 * `max_id`: maximum id
91 * `exclude_replies`: don't show replies (default: false)
92 * `conversation_id`: Shows all statuses of a given conversation.
93 * `include_entities`: "true" shows entities for pictures and links (Default: false)
95 ### GET api/statuses/replies
99 * `count`: Items per page (default: 20)
100 * `page`: page number
101 * `since_id`: minimum id
102 * `max_id`: maximum id
103 * `include_entities`: "true" shows entities for pictures and links (Default: false)
105 #### Unsupported parameters
109 * `contributor_details`
113 ### GET api/conversation/show
115 Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
119 * `id`: id of the post
120 * `count`: Items per page (default: 20)
121 * `page`: page number
122 * `since_id`: minimum id
123 * `max_id`: maximum id
124 * `include_entities`: "true" shows entities for pictures and links (Default: false)
126 #### Unsupported parameters
130 * `contributor_details`
132 ### GET api/statusnet/conversation
134 Alias of [`api/conversation/show`](#GET+api%2Fconversation%2Fshow).
136 ### GET api/statusnet/config
138 Returns the public Friendica node configuration.
140 ### GET api/gnusocial/config
142 Alias of [`api/statusnet/config`](#GET+api%2Fstatusnet%2Fconfig).
144 ### GET api/statusnet/version
146 Returns a fake static StatusNet protocol version.
148 ### GET api/gnusocial/version
150 Alias of [`api/statusnet/version`](#GET+api%2Fstatusnet%2Fversion).
154 ### POST api/friendica/activity/[verb]
156 Add or remove an activity from an item.
157 'verb' can be one of:
165 To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"
166 Attend verbs disable each other: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".
167 Attend verbs should be used only with event-related items (there is no check at the moment).
189 ### GET api/direct_messages
191 Deprecated Twitter received direct message list endpoint.
195 * `count`: Items per page (default: 20)
196 * `page`: page number
197 * `since_id`: minimum id
198 * `max_id`: maximum id
199 * `getText`: Defines the format of the status field. Can be "html" or "plain"
200 * `include_entities`: "true" shows entities for pictures and links (Default: false)
201 * `friendica_verbose`: "true" enables different error returns (default: "false")
203 #### Unsupported parameters
207 ### GET api/direct_messages/all
209 Returns all [Private Messages](help/API-Entities#Private+message).
213 * `count`: Items per page (default: 20)
214 * `page`: page number
215 * `since_id`: minimum id
216 * `max_id`: maximum id
217 * `getText`: Defines the format of the status field. Can be "html" or "plain"
218 * `friendica_verbose`: "true" enables different error returns (default: "false")
220 ### GET api/direct_messages/conversation
222 Returns all replies of a single private message conversation. Returns [Private Messages](help/API-Entities#Private+message)
226 * `count`: Items per page (default: 20)
227 * `page`: page number
228 * `since_id`: minimum id
229 * `max_id`: maximum id
230 * `getText`: Defines the format of the status field. Can be "html" or "plain"
231 * `uri`: URI of the conversation
232 * `friendica_verbose`: "true" enables different error returns (default: "false")
234 ### GET api/direct_messages/sent
236 Deprecated Twitter sent direct message list endpoint. Returns [Private Messages](help/API-Entities#Private+message).
240 * `count`: Items per page (default: 20)
241 * `page`: page number
242 * `since_id`: minimum id
243 * `max_id`: maximum id
244 * `getText`: Defines the format of the status field. Can be "html" or "plain"
245 * `include_entities`: "true" shows entities for pictures and links (Default: false)
246 * `friendica_verbose`: "true" enables different error returns (default: "false")
249 ### POST api/direct_messages/new
251 Deprecated Twitter direct message submission endpoint.
255 * `user_id`: id of the user
256 * `screen_name`: screen name (for technical reasons, this value is not unique!)
257 * `text`: The message
258 * `replyto`: ID of the replied direct message
259 * `title`: Title of the direct message
261 ### POST api/direct_messages/destroy
263 Deprecated Twitter direct message deletion endpoint.
267 * `id`: id of the message to be deleted
268 * `include_entities`: optional, currently not yet implemented
269 * `friendica_parenturi`: optional, can be used for increased safety to delete only intended messages
270 * `friendica_verbose`: "true" enables different error returns (default: "false")
276 * JSON return as defined for Twitter API not yet implemented
277 * on friendica_verbose=true: JSON return {"result":"ok","message":"message deleted"}
282 * on friendica_verbose=true: different JSON returns {"result":"error","message":"xyz"}
284 ### GET api/friendica/direct_messages_setseen
288 * `id`: id of the message to be updated as seen
294 * JSON return `{"result": "ok", "message": "message set to seen"}`
298 * different JSON returns `{"result": "error", "message": "xyz"}`
301 ### GET api/friendica/direct_messages_search (GET; AUTH)
303 Returns [Private Messages](help/API-Entities#Private+message) matching the provided search string.
307 * `searchstring`: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored)
308 * `getText` (optional): `plain`|`html` If omitted, the title is prepended to the plaintext body in the `text` attribute of the private message objects.
309 * `getUserObjects` (optional): `true`|`false` If `false`, the `sender` and `recipient` attributes of the private message object are absent.
313 Returns only tested with JSON, XML might work as well.
317 * JSON return `{"success":"true", "search_results": array of found messages}`
318 * JSOn return `{"success":"false", "search_results": "nothing found"}`
322 * different JSON returns `{"result": "error", "message": "searchstring not specified"}`
326 ### GET api/friendica/circle_show
328 Alternatively: GET api/friendica/group_show (Backward compatibility)
330 Return all or a specified circle of the user with the containing contacts as array.
334 * `gid`: optional, if not given, API returns all circles of the user
340 * `name`: name of the circle
341 * `gid`: id of the circle
342 * `user`: array of [Contacts](help/API-Entities#Contact)
344 ### POST api/friendica/circle_create
346 Alternatively: POST api/friendica/group_create
348 Create the circle with the posted array of contacts as members.
352 * `name`: name of the circle to be created
356 JSON data as Array like the result of [GET api/friendica/circle_show](#GET+api%2Ffriendica%2Fcircle_show):
360 * List of [Contacts](help/API-Entities#Contact)
366 * `success`: true if successfully created or reactivated
367 * `gid`: gid of the created circle
368 * `name`: name of the created circle
369 * `status`: "missing user" | "reactivated" | "ok"
370 * `wrong users`: array of users, which were not available in the contact table
372 ### POST api/friendica/circle_update
374 Alternatively: POST api/friendica/group_update
376 Update the circle with the posted array of contacts as members (post all members of the circle to the call; function will remove members not posted).
380 * `gid`: id of the circle to be changed
381 * `name`: name of the circle to be changed
385 JSON data as array like the result of [GET api/friendica/circle_show](#GET+api%2Ffriendica%2Fcircle_show):
389 * List of [Contacts](help/API-Entities#Contact)
395 * `success`: true if successfully updated
396 * `gid`: gid of the changed circle
397 * `name`: name of the changed circle
398 * `status`: "missing user" | "ok"
399 * `wrong users`: array of users, which were not available in the contact table
401 ### POST api/friendica/circle_delete
403 Alternatively: POST api/friendica/group_delete
405 Delete the specified circle of contacts; API call need to include the correct gid AND name of the circle to be deleted.
409 * `gid`: id of the circle to be deleted
410 * `name`: name of the circle to be deleted
416 * `success`: true if successfully deleted
417 * `gid`: gid of the deleted circle
418 * `name`: name of the deleted circle
419 * `status`: "deleted" if successfully deleted
420 * `wrong users`: empty array
424 ### GET api/friendica/notifications
426 Return last 50 [Notifications](help/API-Entities#Notification) for the current user, ordered by date with unseen item on top.
432 ### POST api/friendica/notifications/seen
434 Set notification as seen.
438 - `id`: id of the notification to set seen
442 If the note is linked to an item, returns an [Item](help/API-Entities#Item).
444 Otherwise, a success status is returned:
446 * `success` (json) | `<status>success</status>` (xml)
450 ### GET api/friendica/photo
452 Returns a [Photo](help/API-Entities#Photo).
456 * `photo_id`: Resource id of a photo.
457 * `scale`: (optional) scale value of the photo
459 Returns data of a picture with the given resource.
460 If 'scale' isn't provided, returned data include full url to each scale of the photo.
461 If 'scale' is set, returned data include image data base64 encoded.
463 possibile scale value are:
465 * 0: original or max size by server settings
466 * 1: image with or height at <= 640
467 * 2: image with or height at <= 320
468 * 3: thumbnail 160x160
469 * 4: Profile image at 300x300
470 * 5: Profile image at 80x80
471 * 6: Profile image at 48x48
473 An image used as profile image has only scale 4-6, other images only 0-3
482 "created": "date(YYYY-MM-DD HH:MM:SS)",
483 "edited": "date(YYYY-MM-DD HH:MM:SS)",
484 "title": "photo title",
485 "desc": "photo description",
486 "album": "album name",
487 "filename": "original file name",
491 "profile": "1 if is profile photo",
493 "<scale>": "url to image",
497 "datasize": "size in byte",
498 "data": "base64 encoded image data"
507 <created>date(YYYY-MM-DD HH:MM:SS)</created>
508 <edited>date(YYYY-MM-DD HH:MM:SS)</edited>
509 <title>photo title</title>
510 <desc>photo description</desc>
511 <album>album name</album>
512 <filename>original file name</filename>
513 <type>mime type</type>
514 <height>number</height>
515 <width>number</width>
516 <profile>1 if is profile photo</profile>
518 <link type="mime type" scale="scale number" href="image url"/>
524 ### GET api/friendica/photos/list
526 Returns the API user's [Photo List Items](help/API-Entities#Photo+List+Item).
536 "album": "album name",
537 "filename": "original file name",
538 "type": "image mime type",
539 "thumb": "url to thumb sized image"
548 <photos type="array">
549 <photo id="resource_id"
551 filename="original file name"
552 type="image mime type">
553 "url to thumb sized image"
559 ### POST api/friendica/photo/create
561 Alias of [`api/friendica/photo/update`](#POST+api%2Ffriendica%2Fphoto%2Fupdate)
563 ### POST api/friendica/photo/update
565 Saves data for the scales 0-2 to database (see above for scale description).
566 Call adds non-public entries to items table to enable authenticated contacts to comment/like the photo.
567 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 circle.
568 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.
572 * `photo_id` (optional): if specified the photo with this id will be updated
573 * `media` (optional): image data as base64, only optional if photo_id is specified (new upload must have media)
574 * `desc` (optional): description for the photo, updated when photo_id is specified
575 * `album`: name of the album to be deleted (always necessary)
576 * `album_new` (optional): can be used to change the album of a single photo if photo_id is specified
577 * `allow_cid`/`allow_gid`/`deny_cid`/`deny_gid` (optional):
578 - on create: empty string or omitting = public photo, specify in format ```<x><y><z>``` for private photo
579 - on update: keys need to be present with empty values for changing a private photo to public
585 * new photo uploaded: JSON return with photo data (see [GET api/friendica/photo](#GET+api%2Ffriendica%2Fphoto))
586 * photo updated - changed photo data: JSON return with photo data (see [GET api/friendica/photo](#GET+api%2Ffriendica%2Fphoto))
587 * photo updated - changed info: JSON return `{"result": "updated", "message":"Image id 'xyz' has been updated."}`
588 * photo updated - nothing changed: JSON return `{"result": "cancelled","message": "Nothing to update for image id 'xyz'."}`
592 * 403 FORBIDDEN: if not authenticated
593 * 400 BADREQUEST: "no albumname specified", "no media data submitted", "photo not available", "acl data invalid"
594 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
595 "image size exceeds Friendica Config setting (uploaded size: x)",
596 "unable to process image data",
597 "image upload failed",
598 "unknown error - uploading photo failed, see Friendica log for more information",
599 "unknown error - update photo entry in database failed",
600 "unknown error - this error on uploading or updating a photo should never happen"
602 ### POST api/friendica/photo/delete
604 Deletes a single image with the specified id, is not reversible -> ensure that client is asking user for being sure to do this
605 Sets item table entries for this photo to deleted = 1.
609 * `photo_id`: id of the photo to be deleted
620 "message": "photo with id 'xyz' has been deleted from server."
626 * 403 FORBIDDEN: if not authenticated
627 * 400 BADREQUEST: "no photo_id specified", "photo not available"
628 * 500 INTERNALSERVERERROR: "unknown error on deleting photo", "problem with deleting items occurred"
632 ### POST api/friendica/photoalbum/delete
634 Deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this.
638 * `album`: name of the album to be deleted
649 "message": "album 'xyz' with all containing photos has been deleted."
655 * 403 FORBIDDEN: if not authenticated
656 * 400 BADREQUEST: "no albumname specified", "album not available"
657 * 500 INTERNALSERVERERROR: "problem with deleting item occurred", "unknown error - deleting from database failed"
659 ### POST api/friendica/photoalbum/update
661 Changes the album name to album_new for all photos in album.
665 * `album`: name of the album to be updated
666 * `album_new`: new name of the album
677 "message":"album 'abc' with all containing photos has been renamed to 'xyz'."
683 * 403 FORBIDDEN: if not authenticated
684 * 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available"
685 * 500 INTERNALSERVERERROR: "unknown error - updating in database failed"
687 ### GET api/friendica/photoalbums
689 Get a list of photo albums for the user
696 On success a list of photo album objects:
701 "name": "Wall Photos",
702 "created": "2023-01-22 02:03:19",
706 "name": "Profile photos",
707 "created": "2022-11-20 14:40:06",
713 ### GET api/friendica/photoalbum
715 Get a list of images in a photo album
718 * `album` (Required): name of the album to be deleted
719 * `limit` (Optional): Maximum number of items to get, defaults to 50, max 500
720 * `offset`(Optional): Offset in results to page through total items, defaults to 0
721 * `latest_first` (Optional): Reverse the order so the most recent images are first, defaults to false
727 * JSON return with the list of Photo items
730 `https://<server>/api/friendica/photoalbum?album=Wall Photos&limit=10&offset=2`
735 "created": "2023-02-14 14:31:06",
736 "edited": "2023-02-14 14:31:14",
739 "album": "Wall Photos",
740 "filename": "image.png",
750 "id": "899184972463eb9b2ae3dc2580502826",
757 "link": "https://<server>/photo/899184972463eb9b2ae3dc2580502826-0.png",
764 "thumb": "https://<server>/photo/899184972463eb9b2ae3dc2580502826-2.png"
773 ### GET api/friendica/profile/show
775 Returns the [Profile](help/API-Entities#Profile) data of the authenticated user.
779 On success: Array of:
781 * `global_dir`: URL of the global directory set in server settings
782 * `friendica_owner`: user data of the authenticated user
783 * `profiles`: array of the profile data
786 HTTP 403 Forbidden: when no authentication was provided
787 HTTP 400 Bad Request: if given profile_id is not in the database or is not assigned to the authenticated user
789 General description of profile data in API returns:
790 - hide_friends: true if friends are hidden
793 - publish: true if published on the server's local directory
794 - net_publish: true if published to global_dir
806 - custom_fields: list of public custom fields
810 ### POST api/friendica/statuses/:id/dislike
812 Marks the given status as disliked by this user
816 * `id`: the status ID that is being marked
820 A Mastodon [Status Entity](https://docs.joinmastodon.org/entities/Status/)
823 `https://<server_name>/api/friendica/statuses/341/dislike`
828 "created_at": "2023-02-23T01:50:00.000Z",
829 "in_reply_to_id": null,
830 "in_reply_to_status": null,
831 "in_reply_to_account_id": null,
834 "visibility": "public",
839 "username": "testuser2",
842 "media_attachments": [],
857 ### GET api/friendica/statuses/:id/disliked_by
859 Returns the list of accounts that have disliked the status as known by the current server
863 * `id`: the status ID that is being marked
867 A list of [Mastodon Account](https://docs.joinmastodon.org/entities/Account/) objects
868 in the body and next/previous link headers in the header
871 `https://<server_name>/api/friendica/statuses/341/disliked_by`
877 "username": "testuser1",
885 ### POST api/friendica/statuses/:id/undislike
887 Removes the dislike mark (if it exists) on this status for this user
891 * `id`: the status ID that is being marked
895 A Mastodon [Status Entity](https://docs.joinmastodon.org/entities/Status/)
898 `https://<server_name>/api/friendica/statuses/341/undislike`
903 "created_at": "2023-02-23T01:50:00.000Z",
904 "in_reply_to_id": null,
905 "in_reply_to_status": null,
906 "in_reply_to_account_id": null,
909 "visibility": "public",
914 "username": "testuser2",
917 "media_attachments": [],
933 ## Deprecated endpoints
935 - POST api/statuses/mediap