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