doc/api.md

   1 Friendica API
   2 ===
   3
   4 * [Home](help)
   5
   6 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).
   7
   8 Please refer to the linked documentation for further information.
   9
  10 ## Implemented API calls
  11
  12 ### General
  13 #### HTTP Method
  14
  15 API endpoints can restrict the method used to request them.
  16 Using an invalid method results in HTTP error 405 "Method Not Allowed".
  17
  18 In this document, the required method is listed after the endpoint name. "*" means every method can be used.
  19
  20 #### Auth
  21
  22 Friendica supports basic http auth and OAuth 1 to authenticate the user to the api.
  23
  24 OAuth settings can be added by the user in web UI under /settings/oauth/
  25
  26 In this document, endpoints which requires auth are marked with "AUTH" after endpoint name
  27
  28 #### Unsupported parameters
  29 * cursor: Not implemented in GNU Social
  30 * trim_user: Not implemented in GNU Social
  31 * contributor_details: Not implemented in GNU Social
  32 * place_id: Not implemented in GNU Social
  33 * display_coordinates: Not implemented in GNU Social
  34 * include_rts: To-Do
  35 * include_my_retweet: Retweets in Friendica are implemented in a different way
  36
  37 #### Different behaviour
  38 * 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.
  39 * include_entities: Default is "false". If set to "true" then the plain text is formatted so that links are having descriptions.
  40
  41 #### Return values
  42 * cid: Contact id of the user (important for "contact_allow" and "contact_deny")
  43 * network: network of the user
  44
  45 #### Errors
  46 When an error occurs in API call, an HTTP error code is returned, with an error message
  47 Usually:
  48 - 400 Bad Request: if parameters are missing or items can't be found
  49 - 403 Forbidden: if the authenticated user is missing
  50 - 405 Method Not Allowed: if API was called with an invalid method, eg. GET when API require POST
  51 - 501 Not Implemented: if the requested API doesn't exist
  52 - 500 Internal Server Error: on other error conditions
  53
  54 Error body is
  55
  56 json:
  57 ```
  58         {
  59                 "error": "Specific error message",
  60                 "request": "API path requested",
  61                 "code": "HTTP error code"
  62         }
  63 ```
  64
  65 xml:
  66 ```
  67         <status>
  68                 <error>Specific error message</error>
  69                 <request>API path requested</request>
  70                 <code>HTTP error code</code>
  71         </status>
  72 ```
  73
  74 ---
  75 ### account/rate_limit_status (*; AUTH)
  76
  77 ---
  78 ### account/verify_credentials (*; AUTH)
  79 #### Parameters
  80
  81 * skip_status: Don't show the "status" field. (Default: false)
  82 * include_entities: "true" shows entities for pictures and links (Default: false)
  83
  84 ---
  85 ### conversation/show (*; AUTH)
  86 Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
  87
  88 #### Parameter
  89 * id: id of the post
  90 * count: Items per page (default: 20)
  91 * page: page number
  92 * since_id: minimum id
  93 * max_id: maximum id
  94 * include_entities: "true" shows entities for pictures and links (Default: false)
  95
  96 #### Unsupported parameters
  97 * include_rts
  98 * trim_user
  99 * contributor_details
 100
 101 ---
 102 ### direct_messages (*; AUTH)
 103 #### Parameters
 104 * count: Items per page (default: 20)
 105 * page: page number
 106 * since_id: minimum id
 107 * max_id: maximum id
 108 * getText: Defines the format of the status field. Can be "html" or "plain"
 109 * include_entities: "true" shows entities for pictures and links (Default: false)
 110 * friendica_verbose: "true" enables different error returns (default: "false")
 111
 112 #### Unsupported parameters
 113 * skip_status
 114
 115 ---
 116 ### direct_messages/all (*; AUTH)
 117 #### Parameters
 118 * count: Items per page (default: 20)
 119 * page: page number
 120 * since_id: minimum id
 121 * max_id: maximum id
 122 * getText: Defines the format of the status field. Can be "html" or "plain"
 123 * friendica_verbose: "true" enables different error returns (default: "false")
 124
 125 ---
 126 ### direct_messages/conversation (*; AUTH)
 127 Shows all direct messages of a conversation
 128 #### Parameters
 129 * count: Items per page (default: 20)
 130 * page: page number
 131 * since_id: minimum id
 132 * max_id: maximum id
 133 * getText: Defines the format of the status field. Can be "html" or "plain"
 134 * uri: URI of the conversation
 135 * friendica_verbose: "true" enables different error returns (default: "false")
 136
 137 ---
 138 ### direct_messages/sent (*; AUTH)
 139 #### Parameters
 140 * count: Items per page (default: 20)
 141 * page: page number
 142 * since_id: minimum id
 143 * max_id: maximum id
 144 * getText: Defines the format of the status field. Can be "html" or "plain"
 145 * include_entities: "true" shows entities for pictures and links (Default: false)
 146 * friendica_verbose: "true" enables different error returns (default: "false")
 147
 148 ---
 149 ### direct_messages/new (POST,PUT; AUTH)
 150 #### Parameters
 151 * user_id: id of the user
 152 * screen_name: screen name (for technical reasons, this value is not unique!)
 153 * text: The message
 154 * replyto: ID of the replied direct message
 155 * title: Title of the direct message
 156
 157 ---
 158 ### direct_messages/destroy (POST,DELETE; AUTH)
 159 #### Parameters
 160 * id: id of the message to be deleted
 161 * include_entities: optional, currently not yet implemented
 162 * friendica_parenturi: optional, can be used for increased safety to delete only intended messages
 163 * friendica_verbose: "true" enables different error returns (default: "false")
 164
 165 #### Return values
 166
 167 On success:
 168 * JSON return as defined for Twitter API not yet implemented
 169 * on friendica_verbose=true: JSON return {"result":"ok","message":"message deleted"}
 170
 171 On error:
 172 HTTP 400 BadRequest
 173 * on friendica_verbose=true: different JSON returns {"result":"error","message":"xyz"}
 174
 175 ---
 176 ### externalprofile/show (*)
 177 #### Parameters
 178 * profileurl: profile url
 179
 180 ---
 181 ### favorites (*; AUTH)
 182 #### Parameters
 183 * count: Items per page (default: 20)
 184 * page: page number
 185 * since_id: minimum id
 186 * max_id: maximum id
 187 * include_entities: "true" shows entities for pictures and links (Default: false)
 188
 189 #### Unsupported parameters
 190 * user_id
 191 * screen_name
 192
 193 Favorites aren't displayed to other users, so "user_id" and "screen_name" are unsupported.
 194 Set this values will result in an empty array.
 195
 196 ---
 197 ### favorites/create (POST,PUT; AUTH)
 198 #### Parameters
 199 * id
 200 * include_entities: "true" shows entities for pictures and links (Default: false)
 201
 202 ---
 203 ### favorites/destroy (POST,DELETE; AUTH)
 204 #### Parameters
 205 * id
 206 * include_entities: "true" shows entities for pictures and links (Default: false)
 207
 208 ---
 209 ### followers/ids (*; AUTH)
 210 #### Parameters
 211 * stringify_ids: Send id numbers as text (true) or integers (false)? (default: false)
 212
 213 #### Unsupported parameters
 214 * user_id
 215 * screen_name
 216 * cursor
 217
 218 Friendica doesn't allow showing the followers of other users.
 219
 220 ---
 221 ### friends/ids (*; AUTH)
 222 #### Parameters
 223 * stringify_ids: Send the id numbers as text (true) or integers (false)? (default: false)
 224
 225 #### Unsupported parameters
 226 * user_id
 227 * screen_name
 228 * cursor
 229
 230 Friendica doesn't allow showing the friends of other users.
 231
 232 ---
 233 ### help/test (*)
 234
 235 ---
 236 ### media/upload (POST,PUT; AUTH)
 237 #### Parameters
 238 * media: image data
 239
 240 ---
 241 ### oauth/request_token (*)
 242 #### Parameters
 243 * oauth_callback
 244
 245 #### Unsupported parameters
 246 * x_auth_access_type
 247
 248 ---
 249 ### oauth/access_token (*)
 250 #### Parameters
 251 * oauth_verifier
 252
 253 #### Unsupported parameters
 254 * x_auth_password
 255 * x_auth_username
 256 * x_auth_mode
 257
 258 ---
 259 ### statuses/destroy (POST,DELETE; AUTH)
 260 #### Parameters
 261 * id: message number
 262 * include_entities: "true" shows entities for pictures and links (Default: false)
 263
 264 #### Unsupported parameters
 265 * trim_user
 266
 267 ---
 268 ### statuses/followers (*; AUTH)
 269
 270 #### Parameters
 271
 272 * include_entities: "true" shows entities for pictures and links (Default: false)
 273
 274 ---
 275 ### statuses/friends (*; AUTH)
 276
 277 #### Parameters
 278
 279 * include_entities: "true" shows entities for pictures and links (Default: false)
 280
 281 ---
 282 ### statuses/friends_timeline (*; AUTH)
 283 #### Parameters
 284 * count: Items per page (default: 20)
 285 * page: page number
 286 * since_id: minimum id
 287 * max_id: maximum id
 288 * exclude_replies: don't show replies (default: false)
 289 * conversation_id: Shows all statuses of a given conversation.
 290 * include_entities: "true" shows entities for pictures and links (Default: false)
 291
 292 #### Unsupported parameters
 293 * include_rts
 294 * trim_user
 295 * contributor_details
 296
 297 ---
 298 ### statuses/home_timeline (*; AUTH)
 299 #### Parameters
 300 * count: Items per page (default: 20)
 301 * page: page number
 302 * since_id: minimum id
 303 * max_id: maximum id
 304 * exclude_replies: don't show replies (default: false)
 305 * conversation_id: Shows all statuses of a given conversation.
 306 * include_entities: "true" shows entities for pictures and links (Default: false)
 307
 308 #### Unsupported parameters
 309 * include_rts
 310 * trim_user
 311 * contributor_details
 312
 313 ---
 314 ### statuses/mentions (*; AUTH)
 315 #### Parameters
 316 * count: Items per page (default: 20)
 317 * page: page number
 318 * since_id: minimum id
 319 * max_id: maximum id
 320 * include_entities: "true" shows entities for pictures and links (Default: false)
 321
 322 #### Unsupported parameters
 323 * include_rts
 324 * trim_user
 325 * contributor_details
 326
 327 ---
 328 ### statuses/public_timeline (*; AUTH)
 329 #### Parameters
 330 * count: Items per page (default: 20)
 331 * page: page number
 332 * since_id: minimum id
 333 * max_id: maximum id
 334 * exclude_replies: don't show replies (default: false)
 335 * conversation_id: Shows all statuses of a given conversation.
 336 * include_entities: "true" shows entities for pictures and links (Default: false)
 337
 338 #### Unsupported parameters
 339 * trim_user
 340
 341 ---
 342 ### statuses/networkpublic_timeline (*; AUTH)
 343 #### Parameters
 344 * count: Items per page (default: 20)
 345 * page: page number
 346 * since_id: minimum id
 347 * max_id: maximum id
 348 * include_entities: "true" shows entities for pictures and links (Default: false)
 349
 350 ---
 351 ### statuses/replies (*; AUTH)
 352 #### Parameters
 353 * count: Items per page (default: 20)
 354 * page: page number
 355 * since_id: minimum id
 356 * max_id: maximum id
 357 * include_entities: "true" shows entities for pictures and links (Default: false)
 358
 359 #### Unsupported parameters
 360 * include_rts
 361 * trim_user
 362 * contributor_details
 363
 364 ---
 365 ### statuses/retweet (POST,PUT; AUTH)
 366 #### Parameters
 367 * id: message number
 368 * include_entities: "true" shows entities for pictures and links (Default: false)
 369
 370 #### Unsupported parameters
 371 * trim_user
 372
 373 ---
 374 ### statuses/show (*; AUTH)
 375 #### Parameters
 376 * id: message number
 377 * conversation: if set to "1" show all messages of the conversation with the given id
 378 * include_entities: "true" shows entities for pictures and links (Default: false)
 379
 380 #### Unsupported parameters
 381 * include_my_retweet
 382 * trim_user
 383
 384 ---
 385 ### statuses/update, statuses/update_with_media
 386 #### Parameters
 387 * title: Title of the status
 388 * status: Status in text format
 389 * htmlstatus: Status in HTML format
 390 * in_reply_to_status_id
 391 * lat: latitude
 392 * long: longitude
 393 * media: image data
 394 * source: Application name
 395 * group_allow
 396 * contact_allow
 397 * group_deny
 398 * contact_deny
 399 * network
 400 * include_entities: "true" shows entities for pictures and links (Default: false)
 401 * media_ids: (By now only a single value, no array)
 402
 403 #### Unsupported parameters
 404 * trim_user
 405 * place_id
 406 * display_coordinates
 407
 408 ---
 409 ### statuses/user_timeline (*; AUTH)
 410 #### Parameters
 411 * user_id: id of the user
 412 * screen_name: screen name (for technical reasons, this value is not unique!)
 413 * count: Items per page (default: 20)
 414 * page: page number
 415 * since_id: minimum id
 416 * max_id: maximum id
 417 * exclude_replies: don't show replies (default: false)
 418 * conversation_id: Shows all statuses of a given conversation.
 419 * include_entities: "true" shows entities for pictures and links (Default: false)
 420
 421 #### Unsupported parameters
 422
 423 * include_rts
 424 * trim_user
 425 * contributor_details
 426
 427 ---
 428 ### statusnet/config (*)
 429
 430 ---
 431 ### statusnet/conversation (*; AUTH)
 432 It shows all direct answers (excluding the original post) to a given id.
 433
 434 #### Parameter
 435 * id: id of the post
 436 * count: Items per page (default: 20)
 437 * page: page number
 438 * since_id: minimum id
 439 * max_id: maximum id
 440 * include_entities: "true" shows entities for pictures and links (Default: false)
 441
 442 ---
 443 ### statusnet/version (*)
 444
 445 #### Unsupported parameters
 446 * user_id
 447 * screen_name
 448 * cursor
 449
 450 Friendica doesn't allow showing followers of other users.
 451
 452 ---
 453 ### users/search (*)
 454 #### Parameters
 455 * q: name of the user
 456
 457 #### Unsupported parameters
 458 * page
 459 * count
 460 * include_entities
 461
 462 ---
 463 ### users/show (*)
 464 #### Parameters
 465 * user_id: id of the user
 466 * screen_name: screen name (for technical reasons, this value is not unique!)
 467 * include_entities: "true" shows entities for pictures and links (Default: false)
 468
 469 #### Unsupported parameters
 470 * user_id
 471 * screen_name
 472 * cursor
 473
 474 Friendica doesn't allow showing friends of other users.
 475
 476
 477 ---
 478 ### account/update_profile_image (POST; AUTH)
 479 #### Parameters
 480 * image: image data as base64 (Twitter has a limit of 700kb, Friendica allows more)
 481 * profile_id (optional): id of the profile for which the image should be used, default is changing the default profile
 482
 483 uploads a new profile image (scales 4-6) to database, changes default or specified profile to the new photo
 484
 485 #### Return values
 486
 487 On success:
 488 * JSON return: returns the updated user details (see account/verify_credentials)
 489
 490 On error:
 491 * 403 FORBIDDEN: if not authenticated
 492 * 400 BADREQUEST: "no media data submitted", "profile_id not available"
 493 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
 494                         "image size exceeds Friendica Config setting (uploaded size: x)",
 495                         "unable to process image data",
 496                         "image upload failed"
 497
 498
 499 ## Implemented API calls (not compatible with other APIs)
 500
 501
 502 ---
 503 ### friendica/activity/<verb>
 504 #### parameters
 505 * id: item id
 506
 507 Add or remove an activity from an item.
 508 'verb' can be one of:
 509
 510 - like
 511 - dislike
 512 - attendyes
 513 - attendno
 514 - attendmaybe
 515
 516 To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"
 517 Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".
 518 Attend verbs should be used only with event-related items (there is no check at the moment)
 519
 520 #### Return values
 521
 522 On success:
 523 json
 524 ```"ok"```
 525
 526 xml
 527 ```<ok>true</ok>```
 528
 529 On error:
 530 HTTP 400 BadRequest
 531
 532 ---
 533 ### friendica/group_show (*; AUTH)
 534 Return all or a specified group of the user with the containing contacts as array.
 535
 536 #### Parameters
 537 * gid: optional, if not given, API returns all groups of the user
 538
 539 #### Return values
 540 Array of:
 541
 542 * name: name of the group
 543 * gid: id of the group
 544 * user: array of group members (return from api_get_user() function for each member)
 545
 546
 547 ---
 548 ### friendica/group_delete (POST,DELETE; AUTH)
 549 delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted.
 550
 551 #### Parameters
 552 * gid: id of the group to be deleted
 553 * name: name of the group to be deleted
 554
 555 #### Return values
 556 Array of:
 557
 558 * success: true if successfully deleted
 559 * gid: gid of the deleted group
 560 * name: name of the deleted group
 561 * status: „deleted“ if successfully deleted
 562 * wrong users: empty array
 563
 564
 565 ---
 566 ### friendica/group_create (POST,PUT; AUTH)
 567 Create the group with the posted array of contacts as members.
 568
 569 #### Parameters
 570 * name: name of the group to be created
 571
 572 #### POST data
 573 JSON data as Array like the result of "users/group_show":
 574
 575 * gid
 576 * name
 577 * array of users
 578
 579 #### Return values
 580 Array of:
 581
 582 * success: true if successfully created or reactivated
 583 * gid: gid of the created group
 584 * name: name of the created group
 585 * status: „missing user“ | „reactivated“ | „ok“
 586 * wrong users: array of users, which were not available in the contact table
 587
 588
 589 ---
 590 ### friendica/group_update (POST)
 591 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).
 592
 593 #### Parameters
 594 * gid: id of the group to be changed
 595 * name: name of the group to be changed
 596
 597 #### POST data
 598 JSON data as array like the result of „users/group_show“:
 599
 600 * gid
 601 * name
 602 * array of users
 603
 604 #### Return values
 605 Array of:
 606
 607 * success: true if successfully updated
 608 * gid: gid of the changed group
 609 * name: name of the changed group
 610 * status: „missing user“ | „ok“
 611 * wrong users: array of users, which were not available in the contact table
 612
 613
 614
 615 ---
 616 ### friendica/notifications (GET)
 617 Return last 50 notification for current user, ordered by date with unseen item on top
 618
 619 #### Parameters
 620 none
 621
 622 #### Return values
 623 Array of:
 624
 625 * id: id of the note
 626 * type: type of notification as int (see NOTIFY_* constants in boot.php)
 627 * name: full name of the contact subject of the note
 628 * url: contact's profile url
 629 * photo: contact's profile photo
 630 * date: datetime string of the note
 631 * timestamp: timestamp of the node
 632 * date_rel: relative date of the note (eg. "1 hour ago")
 633 * msg: note message in bbcode
 634 * msg_html: note message in html
 635 * msg_plain: note message in plain text
 636 * link: link to note
 637 * seen: seen state: 0 or 1
 638
 639
 640 ---
 641 ### friendica/notifications/seen (POST)
 642 Set note as seen, returns item object if possible
 643
 644 #### Parameters
 645 id: id of the note to set seen
 646
 647 #### Return values
 648 If the note is linked to an item, the item is returned, just like one of the "statuses/*_timeline" api.
 649
 650 If the note is not linked to an item, a success status is returned:
 651
 652 * "success" (json) | <status>success</status>;" (xml)
 653
 654
 655 ---
 656 ### friendica/photo (*; AUTH)
 657 #### Parameters
 658 * photo_id: Resource id of a photo.
 659 * scale: (optional) scale value of the photo
 660
 661 Returns data of a picture with the given resource.
 662 If 'scale' isn't provided, returned data include full url to each scale of the photo.
 663 If 'scale' is set, returned data include image data base64 encoded.
 664
 665 possibile scale value are:
 666
 667 * 0: original or max size by server settings
 668 * 1: image with or height at <= 640
 669 * 2: image with or height at <= 320
 670 * 3: thumbnail 160x160
 671 * 4: Profile image at 175x175
 672 * 5: Profile image at 80x80
 673 * 6: Profile image at 48x48
 674
 675 An image used as profile image has only scale 4-6, other images only 0-3
 676
 677 #### Return values
 678
 679 json
 680 ```
 681         {
 682                 "id": "photo id"
 683                 "created": "date(YYYY-MM-DD HH:MM:SS)",
 684                 "edited": "date(YYYY-MM-DD HH:MM:SS)",
 685                 "title": "photo title",
 686                 "desc": "photo description",
 687                 "album": "album name",
 688                 "filename": "original file name",
 689                 "type": "mime type",
 690                 "height": "number",
 691                 "width": "number",
 692                 "profile": "1 if is profile photo",
 693                 "link": {
 694                         "<scale>": "url to image"
 695                         ...
 696                 },
 697                 // if 'scale' is set
 698                 "datasize": "size in byte",
 699                 "data": "base64 encoded image data"
 700         }
 701 ```
 702
 703 xml
 704 ```
 705         <photo>
 706                 <id>photo id</id>
 707                 <created>date(YYYY-MM-DD HH:MM:SS)</created>
 708                 <edited>date(YYYY-MM-DD HH:MM:SS)</edited>
 709                 <title>photo title</title>
 710                 <desc>photo description</desc>
 711                 <album>album name</album>
 712                 <filename>original file name</filename>
 713                 <type>mime type</type>
 714                 <height>number</height>
 715                 <width>number</width>
 716                 <profile>1 if is profile photo</profile>
 717                 <links type="array">
 718                 <link type="mime type" scale="scale number" href="image url"/>
 719                         ...
 720                 </links>
 721         </photo>
 722 ```
 723
 724 ---
 725 ### friendica/photos/list (*; AUTH)
 726
 727 Returns a list of all photo resources of the logged in user.
 728
 729 #### Return values
 730
 731 json
 732 ```
 733         [
 734                 {
 735                         id: "resource_id",
 736                         album: "album name",
 737                         filename: "original file name",
 738                         type: "image mime type",
 739                         thumb: "url to thumb sized image"
 740                 },
 741                 ...
 742         ]
 743 ```
 744
 745 xml
 746 ```
 747         <photos type="array">
 748                 <photo id="resource_id"
 749                 album="album name"
 750                 filename="original file name"
 751                 type="image mime type">
 752                         "url to thumb sized image"
 753                 </photo>
 754                 ...
 755         </photos>
 756 ```
 757
 758 ---
 759 ### friendica/photoalbum/delete (POST,DELETE; AUTH)
 760 #### Parameters
 761 * album: name of the album to be deleted
 762
 763 deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this
 764
 765 #### Return values
 766
 767 On success:
 768 * JSON return {"result":"deleted","message":"album 'xyz' with all containing photos has been deleted."}
 769
 770 On error:
 771 * 403 FORBIDDEN: if not authenticated
 772 * 400 BADREQUEST: "no albumname specified", "album not available"
 773 * 500 INTERNALSERVERERROR: "problem with deleting item occured", "unknown error - deleting from database failed"
 774
 775
 776 ---
 777 ### friendica/photoalbum/update (POST,PUT; AUTH)
 778 #### Parameters
 779 * album: name of the album to be updated
 780 * album_new: new name of the album
 781
 782 changes the album name to album_new for all photos in album
 783
 784 #### Return values
 785
 786 On success:
 787 * JSON return {"result":"updated","message":"album 'abc' with all containing photos has been renamed to 'xyz'."}
 788
 789 On error:
 790 * 403 FORBIDDEN: if not authenticated
 791 * 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available"
 792 * 500 INTERNALSERVERERROR: "unknown error - updating in database failed"
 793
 794
 795 ---
 796 ### friendica/photo/create (POST; AUTH)
 797 ### friendica/photo/update (POST; AUTH)
 798 #### Parameters
 799 * photo_id (optional): if specified the photo with this id will be updated
 800 * media (optional): image data as base64, only optional if photo_id is specified (new upload must have media)
 801 * desc (optional): description for the photo, updated when photo_id is specified
 802 * album: name of the album to be deleted (always necessary)
 803 * album_new (optional): can be used to change the album of a single photo if photo_id is specified
 804 * 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;
 805                         on update: keys need to be present with empty values for changing a private photo to public
 806
 807 both calls point to one function for creating AND updating photos.
 808 Saves data for the scales 0-2 to database (see above for scale description).
 809 Call adds non-visible entries to items table to enable authenticated contacts to comment/like the photo.
 810 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.
 811 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.
 812
 813 #### Return values
 814
 815 On success:
 816 * new photo uploaded: JSON return with photo data (see friendica/photo)
 817 * photo updated - changed photo data: JSON return with photo data (see friendica/photo)
 818 * photo updated - changed info: JSON return {"result":"updated","message":"Image id 'xyz' has been updated."}
 819 * photo updated - nothing changed: JSON return {"result":"cancelled","message":"Nothing to update for image id 'xyz'."}
 820
 821 On error:
 822 * 403 FORBIDDEN: if not authenticated
 823 * 400 BADREQUEST: "no albumname specified", "no media data submitted", "photo not available", "acl data invalid"
 824 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
 825                         "image size exceeds Friendica Config setting (uploaded size: x)",
 826                         "unable to process image data",
 827                         "image upload failed",
 828                         "unknown error - uploading photo failed, see Friendica log for more information",
 829                         "unknown error - update photo entry in database failed",
 830                         "unknown error - this error on uploading or updating a photo should never happen"
 831
 832
 833 ---
 834 ### friendica/photo/delete (DELETE; AUTH)
 835 #### Parameters
 836 * photo_id: id of the photo to be deleted
 837
 838 deletes a single image with the specified id, is not reversible -> ensure that client is asking user for being sure to do this
 839 Sets item table entries for this photo to deleted = 1
 840
 841 #### Return values
 842
 843 On success:
 844 * JSON return {"result":"deleted","message":"photo with id 'xyz' has been deleted from server."}
 845
 846 On error:
 847 * 403 FORBIDDEN: if not authenticated
 848 * 400 BADREQUEST: "no photo_id specified", "photo not available"
 849 * 500 INTERNALSERVERERROR: "unknown error on deleting photo", "problem with deleting items occurred"
 850
 851
 852 ---
 853 ### friendica/direct_messages_setseen (GET; AUTH)
 854 #### Parameters
 855 * id: id of the message to be updated as seen
 856
 857 #### Return values
 858
 859 On success:
 860 * JSON return {"result":"ok","message":"message set to seen"}
 861
 862 On error:
 863 * different JSON returns {"result":"error","message":"xyz"}
 864
 865 ---
 866 ### friendica/direct_messages_search (GET; AUTH)
 867 #### Parameters
 868 * searchstring: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored)
 869
 870 #### Return values
 871 Returns only tested with JSON, XML might work as well.
 872
 873 On success:
 874 * JSON return {"success":"true","search_results": array of found messages}
 875 * JSOn return {"success":"false","search_results":"nothing found"}
 876
 877 On error:
 878 * different JSON returns {"result":"error","message":"searchstring not specified"}
 879
 880 ---
 881 ### friendica/profile/show (GET; AUTH)
 882 show data of all profiles or a single profile of the authenticated user
 883
 884 #### Parameters
 885 * profile_id: id of the profile to be returned (optional, if omitted all profiles are returned by default)
 886
 887 #### Return values
 888 On success: Array of:
 889
 890 * multi_profiles: true if user has activated multi_profiles
 891 * global_dir: URL of the global directory set in server settings
 892 * friendica_owner: user data of the authenticated user
 893 * profiles: array of the profile data
 894
 895 On error:
 896 HTTP 403 Forbidden: when no authentication was provided
 897 HTTP 400 Bad Request: if given profile_id is not in the database or is not assigned to the authenticated user
 898
 899 General description of profile data in API returns:
 900 * profile_id
 901 * profile_name
 902 * is_default: true if this is the public profile
 903 * hide_friends: true if friends are hidden
 904 * profile_photo
 905 * profile_thumb
 906 * publish: true if published on the server's local directory
 907 * net_publish: true if published to global_dir
 908 * description ... homepage: different data fields from 'profile' table in database
 909 * users: array with the users allowed to view this profile (empty if is_default=true)
 910
 911
 912 ---
 913 ## Not Implemented API calls
 914 The following API calls are implemented in GNU Social but not in Friendica: (incomplete)
 915
 916 * statuses/retweets_of_me
 917 * friendships/create
 918 * friendships/destroy
 919 * friendships/exists
 920 * friendships/show
 921 * account/update_profile_background_image
 922 * blocks/create
 923 * blocks/destroy
 924
 925 The following API calls from the Twitter API are not implemented in either Friendica or GNU Social:
 926
 927 * statuses/mentions_timeline
 928 * statuses/retweets/:id
 929 * statuses/oembed
 930 * statuses/retweeters/ids
 931 * statuses/lookup
 932 * direct_messages/show
 933 * search/tweets
 934 * friendships/no_retweets/ids
 935 * friendships/incoming
 936 * friendships/outgoing
 937 * friendships/update
 938 * friends/list
 939 * friendships/lookup
 940 * account/settings
 941 * account/update_delivery_device
 942 * account/update_profile
 943 * account/update_profile_background_image
 944 * blocks/list
 945 * blocks/ids
 946 * users/lookup
 947 * users/show
 948 * users/search
 949 * account/remove_profile_banner
 950 * account/update_profile_banner
 951 * users/profile_banner
 952 * mutes/users/create
 953 * mutes/users/destroy
 954 * mutes/users/ids
 955 * mutes/users/list
 956 * users/suggestions/:slug
 957 * users/suggestions
 958 * users/suggestions/:slug/members
 959 * favorites/list
 960 * lists/list
 961 * lists/statuses
 962 * lists/members/destroy
 963 * lists/memberships
 964 * lists/subscribers
 965 * lists/subscribers/create
 966 * lists/subscribers/show
 967 * lists/subscribers/destroy
 968 * lists/members/create_all
 969 * lists/members/show
 970 * lists/members
 971 * lists/members/create
 972 * lists/destroy
 973 * lists/update
 974 * lists/create
 975 * lists/show
 976 * lists/subscriptions
 977 * lists/members/destroy_all
 978 * lists/ownerships
 979 * saved_searches/list
 980 * saved_searches/show/:id
 981 * saved_searches/create
 982 * saved_searches/destroy/:id
 983 * geo/id/:place_id
 984 * geo/reverse_geocode
 985 * geo/search
 986 * geo/place
 987 * trends/place
 988 * trends/available
 989 * help/configuration
 990 * help/languages
 991 * help/privacy
 992 * help/tos
 993 * trends/closest
 994 * users/report_spam
 995
 996 ---
 997
 998 ---
 999
1000 ## Usage Examples
1001 ### BASH / cURL
1002
1003 /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"
1004
1005 ### Python
1006 The [RSStoFriedika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python.
1007 The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.
1008
1009 def tweet(server, message, group_allow=None):
1010 url = server + '/api/statuses/update'
1011 urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))
1012
1013 There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.