dir/doc/api.md

The friendica API aims to be compatible to the StatusNet API which aims to be compatible to the Twitter API 1.0.

Please refer to the linked documentation for further information.

Implemented API calls

General

Unsupported parameters

• cursor: Not implemented in StatusNet
• trim_user: Not implemented in StatusNet
• contributor_details: Not implemented in StatusNet
• place_id: Not implemented in StatusNet
• display_coordinates: Not implemented in StatusNet
• 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

account/verify_credentials

Parameters

• skip_status: Don't show the "status" field. (Default: false)
• include_entities: "true" shows entities for pictures and links (Default: false)

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)

Unsupported parameters

• trim_user
• place_id
• display_coordinates

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)

statuses/home_timeline

Parameters

• count: Items per page (default: 20)
• page: page number
• since_id: minimal 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/friends_timeline

Parameters

• count: Items per page (default: 20)
• page: page number
• since_id: minimal 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/public_timeline

Parameters

• count: Items per page (default: 20)
• page: page number
• since_id: minimal 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/show

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/retweet

Parameters

• id: message number
• include_entities: "true" shows entities for pictures and links (Default: false)

Unsupported parameters

• trim_user

statuses/destroy

Parameters

• id: message number
• include_entities: "true" shows entities for pictures and links (Default: false)

Unsupported parameters

• trim_user

statuses/mentions

Parameters

• count: Items per page (default: 20)
• page: page number
• since_id: minimal 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/replies

Parameters

• count: Items per page (default: 20)
• page: page number
• since_id: minimal 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/user_timeline

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: minimal 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

conversation/show

Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.

Parameters

• id: id of the post
• count: Items per page (default: 20)
• page: page number
• since_id: minimal id
• max_id: maximum id
• include_entities: "true" shows entities for pictures and links (Default: false)

Unsupported parameters

• include_rts
• trim_user
• contributor_details

favorites

Parameters

• count: Items per page (default: 20)
• page: page number
• since_id: minimal 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". So setting this value will result in an empty array.

account/rate_limit_status

help/test

statuses/friends

• 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.

statuses/followers

• include_entities: "true" shows entities for pictures and links (Default: false)

Unsupported parameters

• user_id
• screen_name
• cursor

Friendica doesn't allow showing followers of other users.

statusnet/config

statusnet/version

friends/ids

Parameters

• stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)

Unsupported parameters

• user_id
• screen_name
• cursor

Friendica doesn't allow showing friends of other users.

followers/ids

Parameters

• stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)

Unsupported parameters

• user_id
• screen_name
• cursor

Friendica doesn't allow showing followers of other users.

direct_messages/new

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/conversation

Shows all direct messages of a conversation

Parameters

• count: Items per page (default: 20)
• page: page number
• since_id: minimal id
• max_id: maximum id
• getText: Defines the format of the status field. Can be "html" or "plain"
• uri: URI of the conversation

direct_messages/all

Parameters

• count: Items per page (default: 20)
• page: page number
• since_id: minimal id
• max_id: maximum id
• getText: Defines the format of the status field. Can be "html" or "plain"

direct_messages/sent

Parameters

• count: Items per page (default: 20)
• page: page number
• since_id: minimal 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)

direct_messages

Parameters

• count: Items per page (default: 20)
• page: page number
• since_id: minimal 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)

Unsupported parameters

• skip_status

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

Not Implemented API calls

The following list is extracted from the API source file (at the very bottom):

• favorites/create
• favorites/destroy
• statuses/retweets_of_me
• friendships/create
• friendships/destroy
• friendships/exists
• friendships/show
• account/update_location
• account/update_profile_background_image
• account/update_profile_image
• blocks/create
• blocks/destroy

The following are things from the Twitter API also not implemented in StatusNet:

• statuses/retweeted_to_me
• statuses/retweeted_by_me
• direct_messages/destroy
• account/end_session
• account/update_delivery_device
• notifications/follow
• notifications/leave
• blocks/exists
• blocks/blocking
• lists

Usage Examples

BASH / cURL

Betamax has documentated some example API usage from a [bash script](https://en.wikipedia.org/wiki/Bash_(Unix_shell) employing curl (see his posting).

/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 RSStoFriedika code can be used as an example of how to use the API with python. The lines for posting are located at line 21 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 for using the API.