diff --git a/doc/api.md b/doc/api.md
new file mode 100644
index 0000000000..f36a79a5eb
--- /dev/null
+++ b/doc/api.md
@@ -0,0 +1,362 @@
+The friendica API aims to be compatible to the [StatusNet API](http://status.net/wiki/Twitter-compatible_API) which aims to be compatible to the [Twitter API 1.0](https://dev.twitter.com/docs/api/1). 
+
+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](https://github.com/friendica/friendica/blob/master/include/api.php) (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](https://en.wikipedia.org/wiki/CURL) (see [his posting](https://betamax65.de/display/betamax65/43539)).
+
+    /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](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.
\ No newline at end of file