1438 lines
31 KiB
Markdown
1438 lines
31 KiB
Markdown
# 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
|
|
|
|
---
|
|
|
|
### Return values for statuses/* api calls
|
|
|
|
Returned status object is conform to GNU Social/Twitter api.
|
|
|
|
Friendica adds some addictional fields:
|
|
|
|
- owner: a user object, it's the owner of the item.
|
|
- private: boolean, true if the item is marked as private
|
|
- activities: map with activities related to the item. Every activity is a list of user objects.
|
|
|
|
This properties are prefixed with "friendica_" in JSON responses and namespaced under "http://friendi.ca/schema/api/1/" in XML responses
|
|
|
|
JSON:
|
|
|
|
```json
|
|
[
|
|
{
|
|
// ...
|
|
'friendica_owner' : {
|
|
// user object
|
|
},
|
|
'friendica_private' : true,
|
|
'friendica_activities': {
|
|
'like': [
|
|
{
|
|
// user object
|
|
},
|
|
// ...
|
|
],
|
|
'dislike': [],
|
|
'attendyes': [],
|
|
'attendno': [],
|
|
'attendmaybe': []
|
|
}
|
|
},
|
|
// ...
|
|
]
|
|
```
|
|
|
|
XML:
|
|
|
|
```xml
|
|
<statuses xmlns="http://api.twitter.com" xmlns:statusnet="http://status.net/schema/api/1/" xmlns:friendica="http://friendi.ca/schema/api/1/" xmlns:georss="http://www.georss.org/georss">
|
|
<status>
|
|
<!-- ... -->
|
|
<friendica:owner><!-- user object --></friendica:owner>
|
|
<friendica:private>true</friendica:private>
|
|
<friendica:activities>
|
|
<friendica:like>
|
|
<user>
|
|
<!-- user object -->
|
|
</user>
|
|
<!-- ... --->
|
|
</friendica:like>
|
|
<friendica:dislike/>
|
|
<friendica:attendyes/>
|
|
<friendica:attendno/>
|
|
<friendica:attendmaybe/>
|
|
</friendica:activities>
|
|
</status>
|
|
<!-- ... -->
|
|
</statuses>
|
|
```
|
|
|
|
|
|
---
|
|
|
|
### 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 300x300
|
|
* 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.
|