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/replies (*; 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 #### Unsupported parameters
 351 * include_rts
 352 * trim_user
 353 * contributor_details
 354
 355 ---
 356 ### statuses/retweet (POST,PUT; AUTH)
 357 #### Parameters
 358 * id: message number
 359 * include_entities: "true" shows entities for pictures and links (Default: false)
 360
 361 #### Unsupported parameters
 362 * trim_user
 363
 364 ---
 365 ### statuses/show (*; AUTH)
 366 #### Parameters
 367 * id: message number
 368 * conversation: if set to "1" show all messages of the conversation with the given id
 369 * include_entities: "true" shows entities for pictures and links (Default: false)
 370
 371 #### Unsupported parameters
 372 * include_my_retweet
 373 * trim_user
 374
 375 ---
 376 ### statuses/update, statuses/update_with_media
 377 #### Parameters
 378 * title: Title of the status
 379 * status: Status in text format
 380 * htmlstatus: Status in HTML format
 381 * in_reply_to_status_id
 382 * lat: latitude
 383 * long: longitude
 384 * media: image data
 385 * source: Application name
 386 * group_allow
 387 * contact_allow
 388 * group_deny
 389 * contact_deny
 390 * network
 391 * include_entities: "true" shows entities for pictures and links (Default: false)
 392 * media_ids: (By now only a single value, no array)
 393
 394 #### Unsupported parameters
 395 * trim_user
 396 * place_id
 397 * display_coordinates
 398
 399 ---
 400 ### statuses/user_timeline (*; AUTH)
 401 #### Parameters
 402 * user_id: id of the user
 403 * screen_name: screen name (for technical reasons, this value is not unique!)
 404 * count: Items per page (default: 20)
 405 * page: page number
 406 * since_id: minimum id
 407 * max_id: maximum id
 408 * exclude_replies: don't show replies (default: false)
 409 * conversation_id: Shows all statuses of a given conversation.
 410 * include_entities: "true" shows entities for pictures and links (Default: false)
 411
 412 #### Unsupported parameters
 413
 414 * include_rts
 415 * trim_user
 416 * contributor_details
 417
 418 ---
 419 ### statusnet/config (*)
 420
 421 ---
 422 ### statusnet/conversation (*; AUTH)
 423 It shows all direct answers (excluding the original post) to a given id.
 424
 425 #### Parameter
 426 * id: id of the post
 427 * count: Items per page (default: 20)
 428 * page: page number
 429 * since_id: minimum id
 430 * max_id: maximum id
 431 * include_entities: "true" shows entities for pictures and links (Default: false)
 432
 433 ---
 434 ### statusnet/version (*)
 435
 436 #### Unsupported parameters
 437 * user_id
 438 * screen_name
 439 * cursor
 440
 441 Friendica doesn't allow showing followers of other users.
 442
 443 ---
 444 ### users/search (*)
 445 #### Parameters
 446 * q: name of the user
 447
 448 #### Unsupported parameters
 449 * page
 450 * count
 451 * include_entities
 452
 453 ---
 454 ### users/show (*)
 455 #### Parameters
 456 * user_id: id of the user
 457 * screen_name: screen name (for technical reasons, this value is not unique!)
 458 * include_entities: "true" shows entities for pictures and links (Default: false)
 459
 460 #### Unsupported parameters
 461 * user_id
 462 * screen_name
 463 * cursor
 464
 465 Friendica doesn't allow showing friends of other users.
 466
 467
 468 ---
 469 ### account/update_profile_image (POST; AUTH)
 470 #### Parameters
 471 * image: image data as base64 (Twitter has a limit of 700kb, Friendica allows more)
 472 * profile_id (optional): id of the profile for which the image should be used, default is changing the default profile
 473
 474 uploads a new profile image (scales 4-6) to database, changes default or specified profile to the new photo
 475
 476 #### Return values
 477
 478 On success:
 479 * JSON return: returns the updated user details (see account/verify_credentials)
 480
 481 On error:
 482 * 403 FORBIDDEN: if not authenticated
 483 * 400 BADREQUEST: "no media data submitted", "profile_id not available"
 484 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
 485                         "image size exceeds Friendica Config setting (uploaded size: x)",
 486                         "unable to process image data",
 487                         "image upload failed"
 488
 489
 490 ## Implemented API calls (not compatible with other APIs)
 491
 492
 493 ---
 494 ### friendica/activity/<verb>
 495 #### parameters
 496 * id: item id
 497
 498 Add or remove an activity from an item.
 499 'verb' can be one of:
 500
 501 - like
 502 - dislike
 503 - attendyes
 504 - attendno
 505 - attendmaybe
 506
 507 To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"
 508 Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".
 509 Attend verbs should be used only with event-related items (there is no check at the moment)
 510
 511 #### Return values
 512
 513 On success:
 514 json
 515 ```"ok"```
 516
 517 xml
 518 ```<ok>true</ok>```
 519
 520 On error:
 521 HTTP 400 BadRequest
 522
 523 ---
 524 ### friendica/group_show (*; AUTH)
 525 Return all or a specified group of the user with the containing contacts as array.
 526
 527 #### Parameters
 528 * gid: optional, if not given, API returns all groups of the user
 529
 530 #### Return values
 531 Array of:
 532
 533 * name: name of the group
 534 * gid: id of the group
 535 * user: array of group members (return from api_get_user() function for each member)
 536
 537
 538 ---
 539 ### friendica/group_delete (POST,DELETE; AUTH)
 540 delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted.
 541
 542 #### Parameters
 543 * gid: id of the group to be deleted
 544 * name: name of the group to be deleted
 545
 546 #### Return values
 547 Array of:
 548
 549 * success: true if successfully deleted
 550 * gid: gid of the deleted group
 551 * name: name of the deleted group
 552 * status: „deleted“ if successfully deleted
 553 * wrong users: empty array
 554
 555
 556 ---
 557 ### friendica/group_create (POST,PUT; AUTH)
 558 Create the group with the posted array of contacts as members.
 559
 560 #### Parameters
 561 * name: name of the group to be created
 562
 563 #### POST data
 564 JSON data as Array like the result of "users/group_show":
 565
 566 * gid
 567 * name
 568 * array of users
 569
 570 #### Return values
 571 Array of:
 572
 573 * success: true if successfully created or reactivated
 574 * gid: gid of the created group
 575 * name: name of the created group
 576 * status: „missing user“ | „reactivated“ | „ok“
 577 * wrong users: array of users, which were not available in the contact table
 578
 579
 580 ---
 581 ### friendica/group_update (POST)
 582 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).
 583
 584 #### Parameters
 585 * gid: id of the group to be changed
 586 * name: name of the group to be changed
 587
 588 #### POST data
 589 JSON data as array like the result of „users/group_show“:
 590
 591 * gid
 592 * name
 593 * array of users
 594
 595 #### Return values
 596 Array of:
 597
 598 * success: true if successfully updated
 599 * gid: gid of the changed group
 600 * name: name of the changed group
 601 * status: „missing user“ | „ok“
 602 * wrong users: array of users, which were not available in the contact table
 603
 604
 605
 606 ---
 607 ### friendica/notifications (GET)
 608 Return last 50 notification for current user, ordered by date with unseen item on top
 609
 610 #### Parameters
 611 none
 612
 613 #### Return values
 614 Array of:
 615
 616 * id: id of the note
 617 * type: type of notification as int (see NOTIFY_* constants in boot.php)
 618 * name: full name of the contact subject of the note
 619 * url: contact's profile url
 620 * photo: contact's profile photo
 621 * date: datetime string of the note
 622 * timestamp: timestamp of the node
 623 * date_rel: relative date of the note (eg. "1 hour ago")
 624 * msg: note message in bbcode
 625 * msg_html: note message in html
 626 * msg_plain: note message in plain text
 627 * link: link to note
 628 * seen: seen state: 0 or 1
 629
 630
 631 ---
 632 ### friendica/notifications/seen (POST)
 633 Set note as seen, returns item object if possible
 634
 635 #### Parameters
 636 id: id of the note to set seen
 637
 638 #### Return values
 639 If the note is linked to an item, the item is returned, just like one of the "statuses/*_timeline" api.
 640
 641 If the note is not linked to an item, a success status is returned:
 642
 643 * "success" (json) | <status>success</status>;" (xml)
 644
 645
 646 ---
 647 ### friendica/photo (*; AUTH)
 648 #### Parameters
 649 * photo_id: Resource id of a photo.
 650 * scale: (optional) scale value of the photo
 651
 652 Returns data of a picture with the given resource.
 653 If 'scale' isn't provided, returned data include full url to each scale of the photo.
 654 If 'scale' is set, returned data include image data base64 encoded.
 655
 656 possibile scale value are:
 657
 658 * 0: original or max size by server settings
 659 * 1: image with or height at <= 640
 660 * 2: image with or height at <= 320
 661 * 3: thumbnail 160x160
 662 * 4: Profile image at 175x175
 663 * 5: Profile image at 80x80
 664 * 6: Profile image at 48x48
 665
 666 An image used as profile image has only scale 4-6, other images only 0-3
 667
 668 #### Return values
 669
 670 json
 671 ```
 672         {
 673                 "id": "photo id"
 674                 "created": "date(YYYY-MM-DD HH:MM:SS)",
 675                 "edited": "date(YYYY-MM-DD HH:MM:SS)",
 676                 "title": "photo title",
 677                 "desc": "photo description",
 678                 "album": "album name",
 679                 "filename": "original file name",
 680                 "type": "mime type",
 681                 "height": "number",
 682                 "width": "number",
 683                 "profile": "1 if is profile photo",
 684                 "link": {
 685                         "<scale>": "url to image"
 686                         ...
 687                 },
 688                 // if 'scale' is set
 689                 "datasize": "size in byte",
 690                 "data": "base64 encoded image data"
 691         }
 692 ```
 693
 694 xml
 695 ```
 696         <photo>
 697                 <id>photo id</id>
 698                 <created>date(YYYY-MM-DD HH:MM:SS)</created>
 699                 <edited>date(YYYY-MM-DD HH:MM:SS)</edited>
 700                 <title>photo title</title>
 701                 <desc>photo description</desc>
 702                 <album>album name</album>
 703                 <filename>original file name</filename>
 704                 <type>mime type</type>
 705                 <height>number</height>
 706                 <width>number</width>
 707                 <profile>1 if is profile photo</profile>
 708                 <links type="array">
 709                 <link type="mime type" scale="scale number" href="image url"/>
 710                         ...
 711                 </links>
 712         </photo>
 713 ```
 714
 715 ---
 716 ### friendica/photos/list (*; AUTH)
 717
 718 Returns a list of all photo resources of the logged in user.
 719
 720 #### Return values
 721
 722 json
 723 ```
 724         [
 725                 {
 726                         id: "resource_id",
 727                         album: "album name",
 728                         filename: "original file name",
 729                         type: "image mime type",
 730                         thumb: "url to thumb sized image"
 731                 },
 732                 ...
 733         ]
 734 ```
 735
 736 xml
 737 ```
 738         <photos type="array">
 739                 <photo id="resource_id"
 740                 album="album name"
 741                 filename="original file name"
 742                 type="image mime type">
 743                         "url to thumb sized image"
 744                 </photo>
 745                 ...
 746         </photos>
 747 ```
 748
 749 ---
 750 ### friendica/photoalbum/delete (POST,DELETE; AUTH)
 751 #### Parameters
 752 * album: name of the album to be deleted
 753
 754 deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this
 755
 756 #### Return values
 757
 758 On success:
 759 * JSON return {"result":"deleted","message":"album 'xyz' with all containing photos has been deleted."}
 760
 761 On error:
 762 * 403 FORBIDDEN: if not authenticated
 763 * 400 BADREQUEST: "no albumname specified", "album not available"
 764 * 500 INTERNALSERVERERROR: "problem with deleting item occured", "unknown error - deleting from database failed"
 765
 766
 767 ---
 768 ### friendica/photoalbum/update (POST,PUT; AUTH)
 769 #### Parameters
 770 * album: name of the album to be updated
 771 * album_new: new name of the album
 772
 773 changes the album name to album_new for all photos in album
 774
 775 #### Return values
 776
 777 On success:
 778 * JSON return {"result":"updated","message":"album 'abc' with all containing photos has been renamed to 'xyz'."}
 779
 780 On error:
 781 * 403 FORBIDDEN: if not authenticated
 782 * 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available"
 783 * 500 INTERNALSERVERERROR: "unknown error - updating in database failed"
 784
 785
 786 ---
 787 ### friendica/photo/create (POST; AUTH)
 788 ### friendica/photo/update (POST; AUTH)
 789 #### Parameters
 790 * photo_id (optional): if specified the photo with this id will be updated
 791 * media (optional): image data as base64, only optional if photo_id is specified (new upload must have media)
 792 * desc (optional): description for the photo, updated when photo_id is specified
 793 * album: name of the album to be deleted (always necessary)
 794 * album_new (optional): can be used to change the album of a single photo if photo_id is specified
 795 * 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;
 796                         on update: keys need to be present with empty values for changing a private photo to public
 797
 798 both calls point to one function for creating AND updating photos.
 799 Saves data for the scales 0-2 to database (see above for scale description).
 800 Call adds non-visible entries to items table to enable authenticated contacts to comment/like the photo.
 801 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.
 802 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.
 803
 804 #### Return values
 805
 806 On success:
 807 * new photo uploaded: JSON return with photo data (see friendica/photo)
 808 * photo updated - changed photo data: JSON return with photo data (see friendica/photo)
 809 * photo updated - changed info: JSON return {"result":"updated","message":"Image id 'xyz' has been updated."}
 810 * photo updated - nothing changed: JSON return {"result":"cancelled","message":"Nothing to update for image id 'xyz'."}
 811
 812 On error:
 813 * 403 FORBIDDEN: if not authenticated
 814 * 400 BADREQUEST: "no albumname specified", "no media data submitted", "photo not available", "acl data invalid"
 815 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
 816                         "image size exceeds Friendica Config setting (uploaded size: x)",
 817                         "unable to process image data",
 818                         "image upload failed",
 819                         "unknown error - uploading photo failed, see Friendica log for more information",
 820                         "unknown error - update photo entry in database failed",
 821                         "unknown error - this error on uploading or updating a photo should never happen"
 822
 823
 824 ---
 825 ### friendica/photo/delete (DELETE; AUTH)
 826 #### Parameters
 827 * photo_id: id of the photo to be deleted
 828
 829 deletes a single image with the specified id, is not reversible -> ensure that client is asking user for being sure to do this
 830 Sets item table entries for this photo to deleted = 1
 831
 832 #### Return values
 833
 834 On success:
 835 * JSON return {"result":"deleted","message":"photo with id 'xyz' has been deleted from server."}
 836
 837 On error:
 838 * 403 FORBIDDEN: if not authenticated
 839 * 400 BADREQUEST: "no photo_id specified", "photo not available"
 840 * 500 INTERNALSERVERERROR: "unknown error on deleting photo", "problem with deleting items occurred"
 841
 842
 843 ---
 844 ### friendica/direct_messages_setseen (GET; AUTH)
 845 #### Parameters
 846 * id: id of the message to be updated as seen
 847
 848 #### Return values
 849
 850 On success:
 851 * JSON return {"result":"ok","message":"message set to seen"}
 852
 853 On error:
 854 * different JSON returns {"result":"error","message":"xyz"}
 855
 856 ---
 857 ### friendica/direct_messages_search (GET; AUTH)
 858 #### Parameters
 859 * searchstring: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored)
 860
 861 #### Return values
 862 Returns only tested with JSON, XML might work as well.
 863
 864 On success:
 865 * JSON return {"success":"true","search_results": array of found messages}
 866 * JSOn return {"success":"false","search_results":"nothing found"}
 867
 868 On error:
 869 * different JSON returns {"result":"error","message":"searchstring not specified"}
 870
 871 ---
 872 ### friendica/profile/show (GET; AUTH)
 873 show data of all profiles or a single profile of the authenticated user
 874
 875 #### Parameters
 876 * profile_id: id of the profile to be returned (optional, if omitted all profiles are returned by default)
 877
 878 #### Return values
 879 On success: Array of:
 880
 881 * multi_profiles: true if user has activated multi_profiles
 882 * global_dir: URL of the global directory set in server settings
 883 * friendica_owner: user data of the authenticated user
 884 * profiles: array of the profile data
 885
 886 On error:
 887 HTTP 403 Forbidden: when no authentication was provided
 888 HTTP 400 Bad Request: if given profile_id is not in the database or is not assigned to the authenticated user
 889
 890 General description of profile data in API returns:
 891 * profile_id
 892 * profile_name
 893 * is_default: true if this is the public profile
 894 * hide_friends: true if friends are hidden
 895 * profile_photo
 896 * profile_thumb
 897 * publish: true if published on the server's local directory
 898 * net_publish: true if published to global_dir
 899 * description ... homepage: different data fields from 'profile' table in database
 900 * users: array with the users allowed to view this profile (empty if is_default=true)
 901
 902
 903 ---
 904 ## Not Implemented API calls
 905 The following API calls are implemented in GNU Social but not in Friendica: (incomplete)
 906
 907 * statuses/retweets_of_me
 908 * friendships/create
 909 * friendships/destroy
 910 * friendships/exists
 911 * friendships/show
 912 * account/update_profile_background_image
 913 * blocks/create
 914 * blocks/destroy
 915
 916 The following API calls from the Twitter API are not implemented in either Friendica or GNU Social:
 917
 918 * statuses/mentions_timeline
 919 * statuses/retweets/:id
 920 * statuses/oembed
 921 * statuses/retweeters/ids
 922 * statuses/lookup
 923 * direct_messages/show
 924 * search/tweets
 925 * friendships/no_retweets/ids
 926 * friendships/incoming
 927 * friendships/outgoing
 928 * friendships/update
 929 * friends/list
 930 * friendships/lookup
 931 * account/settings
 932 * account/update_delivery_device
 933 * account/update_profile
 934 * account/update_profile_background_image
 935 * blocks/list
 936 * blocks/ids
 937 * users/lookup
 938 * users/show
 939 * users/search
 940 * account/remove_profile_banner
 941 * account/update_profile_banner
 942 * users/profile_banner
 943 * mutes/users/create
 944 * mutes/users/destroy
 945 * mutes/users/ids
 946 * mutes/users/list
 947 * users/suggestions/:slug
 948 * users/suggestions
 949 * users/suggestions/:slug/members
 950 * favorites/list
 951 * lists/list
 952 * lists/statuses
 953 * lists/members/destroy
 954 * lists/memberships
 955 * lists/subscribers
 956 * lists/subscribers/create
 957 * lists/subscribers/show
 958 * lists/subscribers/destroy
 959 * lists/members/create_all
 960 * lists/members/show
 961 * lists/members
 962 * lists/members/create
 963 * lists/destroy
 964 * lists/update
 965 * lists/create
 966 * lists/show
 967 * lists/subscriptions
 968 * lists/members/destroy_all
 969 * lists/ownerships
 970 * saved_searches/list
 971 * saved_searches/show/:id
 972 * saved_searches/create
 973 * saved_searches/destroy/:id
 974 * geo/id/:place_id
 975 * geo/reverse_geocode
 976 * geo/search
 977 * geo/place
 978 * trends/place
 979 * trends/available
 980 * help/configuration
 981 * help/languages
 982 * help/privacy
 983 * help/tos
 984 * trends/closest
 985 * users/report_spam
 986
 987 ---
 988
 989 ---
 990
 991 ## Usage Examples
 992 ### BASH / cURL
 993
 994 /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"
 995
 996 ### Python
 997 The [RSStoFriedika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python.
 998 The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.
 999
1000 def tweet(server, message, group_allow=None):
1001 url = server + '/api/statuses/update'
1002 urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))
1003
1004 There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.