test1.freedica.com
Friendica provides the following specific endpoints.
Authentication is the same as described in Using the APIs.
These endpoints uses the Friendica API entities.
Returns a list of Event entities for the current logged in user.
since_id: (optional) minimum event id for paginationcount: maximum number of items returned, default 20Create a new event for the current logged in user.
id : (optional) id of event, event will be amended if suppliedname : name of the event (required)start_time : start of the event (ISO), requiredend_time : (optional) end of the event, event is open end, if not supplieddesc : (optional) description of the eventplace : (optional) location of the eventpublish : (optional) create message for eventallow_cid : (optional) ACL-formatted list of allowed contact ids if private eventallow_gid : (optional) ACL-formatted list of disallowed contact ids if private eventdeny_cid : (optional) ACL-formatted list of allowed circle ids if private eventdeny_gid : (optional) ACL-formatted list of disallowed circle ids if private eventDelete event from calendar (not the message)
id : id of event to be deletedReturns a Contact entity for the provided profile URL.
profileurl: Profile URLReturns a list of public Items posted on this node. Equivalent of the local community page.
count: Items per page (default: 20)page: page numbersince_id: minimum idmax_id: maximum idexclude_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)trim_userReturns a list of public Items this node is aware of. Equivalent of the global community page.
count: Items per page (default: 20)page: page numbersince_id: minimum idmax_id: maximum idexclude_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)count: Items per page (default: 20)page: page numbersince_id: minimum idmax_id: maximum idinclude_entities: "true" shows entities for pictures and links (Default: false)include_rtstrim_usercontributor_detailsUnofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
id: id of the postcount: Items per page (default: 20)page: page numbersince_id: minimum idmax_id: maximum idinclude_entities: "true" shows entities for pictures and links (Default: false)include_rtstrim_usercontributor_detailsAlias of api/conversation/show.
Returns the public Friendica node configuration.
Alias of api/statusnet/config.
Returns a fake static StatusNet protocol version.
Alias of api/statusnet/version.
Add or remove an activity from an item. 'verb' can be one of:
likedislikeattendyesattendnoattendmaybeTo remove an activity, prepend the verb with "un", eg. "unlike" or "undislike" Attend verbs disable each other: 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).
id: item idOn success: json:
"ok"
xml:
<ok>true</ok>
On error: HTTP 400 BadRequest
Deprecated Twitter received direct message list endpoint.
count: Items per page (default: 20)page: page numbersince_id: minimum idmax_id: maximum idgetText: 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")skip_statusReturns all Private Messages.
count: Items per page (default: 20)page: page numbersince_id: minimum idmax_id: maximum idgetText: Defines the format of the status field. Can be "html" or "plain"friendica_verbose: "true" enables different error returns (default: "false")Returns all replies of a single private message conversation. Returns Private Messages
count: Items per page (default: 20)page: page numbersince_id: minimum idmax_id: maximum idgetText: Defines the format of the status field. Can be "html" or "plain"uri: URI of the conversationfriendica_verbose: "true" enables different error returns (default: "false")Deprecated Twitter sent direct message list endpoint. Returns Private Messages.
count: Items per page (default: 20)page: page numbersince_id: minimum idmax_id: maximum idgetText: 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")Deprecated Twitter direct message submission endpoint.
user_id: id of the userscreen_name: screen name (for technical reasons, this value is not unique!)text: The messagereplyto: ID of the replied direct messagetitle: Title of the direct messageDeprecated Twitter direct message deletion endpoint.
id: id of the message to be deletedinclude_entities: optional, currently not yet implementedfriendica_parenturi: optional, can be used for increased safety to delete only intended messagesfriendica_verbose: "true" enables different error returns (default: "false")On success:
On error: HTTP 400 BadRequest
id: id of the message to be updated as seenOn success:
{"result": "ok", "message": "message set to seen"}On error:
{"result": "error", "message": "xyz"}Returns Private Messages matching the provided search string.
searchstring: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored)getText (optional): plain|html If omitted, the title is prepended to the plaintext body in the text attribute of the private message objects.getUserObjects (optional): true|false If false, the sender and recipient attributes of the private message object are absent.Returns only tested with JSON, XML might work as well.
On success:
{"success":"true", "search_results": array of found messages}{"success":"false", "search_results": "nothing found"}On error:
{"result": "error", "message": "searchstring not specified"}Alternatively: GET api/friendica/group_show (Backward compatibility)
Return all or a specified circle of the user with the containing contacts as array.
gid: optional, if not given, API returns all circles of the userArray of:
name: name of the circlegid: id of the circleuser: array of ContactsAlternatively: POST api/friendica/group_create
Create the circle with the posted array of contacts as members.
name: name of the circle to be createdJSON data as Array like the result of GET api/friendica/circle_show:
gidnameArray of:
success: true if successfully created or reactivatedgid: gid of the created circlename: name of the created circlestatus: "missing user" | "reactivated" | "ok"wrong users: array of users, which were not available in the contact tableAlternatively: POST api/friendica/group_update
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).
gid: id of the circle to be changedname: name of the circle to be changedJSON data as array like the result of GET api/friendica/circle_show:
gidnameArray of:
success: true if successfully updatedgid: gid of the changed circlename: name of the changed circlestatus: "missing user" | "ok"wrong users: array of users, which were not available in the contact tableAlternatively: POST api/friendica/group_delete
Delete the specified circle of contacts; API call need to include the correct gid AND name of the circle to be deleted.
gid: id of the circle to be deletedname: name of the circle to be deletedArray of:
success: true if successfully deletedgid: gid of the deleted circlename: name of the deleted circlestatus: "deleted" if successfully deletedwrong users: empty arrayReturn last 50 Notifications for the current user, ordered by date with unseen item on top.
none
Set notification as seen.
id: id of the notification to set seenIf the note is linked to an item, returns an Item.
Otherwise, a success status is returned:
success (json) | <status>success</status> (xml)Returns a Photo.
photo_id: Resource id of a photo.scale: (optional) scale value of the photoReturns 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:
An image used as profile image has only scale 4-6, other images only 0-3
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:
<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>
Returns the API user's Photo List Items.
json:
[
{
"id": "resource_id",
"album": "album name",
"filename": "original file name",
"type": "image mime type",
"thumb": "url to thumb sized image"
},
...
]
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>
Alias of api/friendica/photo/update
Saves data for the scales 0-2 to database (see above for scale description). Call adds non-public 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 circle. 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.
photo_id (optional): if specified the photo with this id will be updatedmedia (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 specifiedalbum: 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 specifiedallow_cid/allow_gid/deny_cid/deny_gid (optional):
<x><y><z> for private photoOn success:
{"result": "updated", "message":"Image id 'xyz' has been updated."}{"result": "cancelled","message": "Nothing to update for image id 'xyz'."}On error:
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.
photo_id: id of the photo to be deletedOn success:
{
"result": "deleted",
"message": "photo with id 'xyz' has been deleted from server."
}
On error:
Deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this.
album: name of the album to be deletedOn success:
{
"result": "deleted",
"message": "album 'xyz' with all containing photos has been deleted."
}
On error:
Changes the album name to album_new for all photos in album.
album: name of the album to be updatedalbum_new: new name of the albumOn success:
{
"result": "updated",
"message":"album 'abc' with all containing photos has been renamed to 'xyz'."
}
On error:
Get a list of photo albums for the user
None
On success a list of photo album objects:
[
{
"name": "Wall Photos",
"created": "2023-01-22 02:03:19",
"count": 4
},
{
"name": "Profile photos",
"created": "2022-11-20 14:40:06",
"count": 1
}
]
Get a list of images in a photo album
album (Required): name of the album to be deletedlimit (Optional): Maximum number of items to get, defaults to 50, max 500offset(Optional): Offset in results to page through total items, defaults to 0latest_first (Optional): Reverse the order so the most recent images are first, defaults to falseOn success:
Example:
https://<server>/api/friendica/photoalbum?album=Wall Photos&limit=10&offset=2
[
{
"created": "2023-02-14 14:31:06",
"edited": "2023-02-14 14:31:14",
"title": "",
"desc": "",
"album": "Wall Photos",
"filename": "image.png",
"type": "image/png",
"height": 835,
"width": 693,
"datasize": 119523,
"profile": 0,
"allow_cid": "",
"deny_cid": "",
"allow_gid": "",
"deny_gid": "",
"id": "899184972463eb9b2ae3dc2580502826",
"scale": 0,
"media-id": 52,
"scales": [
{
"id": 52,
"scale": 0,
"link": "https://<server>/photo/899184972463eb9b2ae3dc2580502826-0.png",
"width": 693,
"height": 835,
"size": 119523
},
...
],
"thumb": "https://<server>/photo/899184972463eb9b2ae3dc2580502826-2.png"
},
...
]
Returns the Profile data of the authenticated user.
On success: Array of:
global_dir: URL of the global directory set in server settingsfriendica_owner: user data of the authenticated userprofiles: array of the profile dataOn 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: - 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 - fullname - date_of_birth - description - xmpp - homepage - address - locality - region - postal_code - country - pub_keywords - custom_fields: list of public custom fields
Marks the given status as disliked by this user
id: the status ID that is being markedA Mastodon Status Entity
https://<server_name>/api/friendica/statuses/341/dislike
{
"id": "341",
"created_at": "2023-02-23T01:50:00.000Z",
"in_reply_to_id": null,
"in_reply_to_status": null,
"in_reply_to_account_id": null,
"sensitive": false,
"spoiler_text": "",
"visibility": "public",
"language": "en",
...
"account": {
"id": "8",
"username": "testuser2",
...
},
"media_attachments": [],
"mentions": [],
"tags": [],
"emojis": [],
"card": null,
"poll": null,
"friendica": {
"title": "",
"dislikes_count": 1,
"disliked": true
}
}
Returns the list of accounts that have disliked the status as known by the current server
id: the status ID that is being markedA list of Mastodon Account objects in the body and next/previous link headers in the header
https://<server_name>/api/friendica/statuses/341/disliked_by
[
{
"id": "6",
"username": "testuser1",
...
}
]
Removes the dislike mark (if it exists) on this status for this user
id: the status ID that is being markedA Mastodon Status Entity
https://<server_name>/api/friendica/statuses/341/undislike
{
"id": "341",
"created_at": "2023-02-23T01:50:00.000Z",
"in_reply_to_id": null,
"in_reply_to_status": null,
"in_reply_to_account_id": null,
"sensitive": false,
"spoiler_text": "",
"visibility": "public",
"language": "en",
...
"account": {
"id": "8",
"username": "testuser2",
...
},
"media_attachments": [],
"mentions": [],
"tags": [],
"emojis": [],
"card": null,
"poll": null,
"friendica": {
"title": "",
"dislikes_count": 0,
"disliked": false
}
}