doc/api.md

   1 # Friendica API
   2
   3 <!-- markdownlint-disable MD010 MD013 MD024 -->
   4
   5 * [Home](help)
   6
   7 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).
   8
   9 Please refer to the linked documentation for further information.
  10
  11 ## Implemented API calls
  12
  13 ### General
  14
  15 #### HTTP Method
  16
  17 API endpoints can restrict the method used to request them.
  18 Using an invalid method results in HTTP error 405 "Method Not Allowed".
  19
  20 In this document, the required method is listed after the endpoint name. "*" means every method can be used.
  21
  22 #### Auth
  23
  24 Friendica supports basic http auth and OAuth 1 to authenticate the user to the api.
  25
  26 OAuth settings can be added by the user in web UI under /settings/oauth/
  27
  28 In this document, endpoints which requires auth are marked with "AUTH" after endpoint name
  29
  30 #### Unsupported parameters
  31
  32 * cursor: Not implemented in GNU Social
  33 * trim_user: Not implemented in GNU Social
  34 * contributor_details: Not implemented in GNU Social
  35 * place_id: Not implemented in GNU Social
  36 * display_coordinates: Not implemented in GNU Social
  37 * include_rts: To-Do
  38 * include_my_retweet: Retweets in Friendica are implemented in a different way
  39
  40 #### Different behaviour
  41
  42 * 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.
  43 * include_entities: Default is "false". If set to "true" then the plain text is formatted so that links are having descriptions.
  44
  45 #### Return values
  46
  47 * cid: Contact id of the user (important for "contact_allow" and "contact_deny")
  48 * network: network of the user
  49
  50 #### Errors
  51
  52 When an error occurs in API call, an HTTP error code is returned, with an error message
  53 Usually:
  54
  55 * 400 Bad Request: if parameters are missing or items can't be found
  56 * 403 Forbidden: if the authenticated user is missing
  57 * 405 Method Not Allowed: if API was called with an invalid method, eg. GET when API require POST
  58 * 501 Not Implemented: if the requested API doesn't exist
  59 * 500 Internal Server Error: on other error conditions
  60
  61 Error body is
  62
  63 json:
  64
  65 ```json
  66         {
  67                 "error": "Specific error message",
  68                 "request": "API path requested",
  69                 "code": "HTTP error code"
  70         }
  71 ```
  72
  73 xml:
  74
  75 ```xml
  76         <status>
  77                 <error>Specific error message</error>
  78                 <request>API path requested</request>
  79                 <code>HTTP error code</code>
  80         </status>
  81 ```
  82
  83 ---
  84
  85 ### account/rate_limit_status (*; AUTH)
  86
  87 ---
  88
  89 ### account/verify_credentials (*; AUTH)
  90
  91 #### Parameters
  92
  93 * skip_status: Don't show the "status" field. (Default: false)
  94 * include_entities: "true" shows entities for pictures and links (Default: false)
  95
  96 ---
  97
  98 ### conversation/show (*; AUTH)
  99
 100 Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
 101
 102 #### Parameter
 103
 104 * id: id of the post
 105 * count: Items per page (default: 20)
 106 * page: page number
 107 * since_id: minimum id
 108 * max_id: maximum id
 109 * include_entities: "true" shows entities for pictures and links (Default: false)
 110
 111 #### Unsupported parameters
 112
 113 * include_rts
 114 * trim_user
 115 * contributor_details
 116
 117 ---
 118
 119 ### direct_messages (*; AUTH)
 120
 121 #### Parameters
 122
 123 * count: Items per page (default: 20)
 124 * page: page number
 125 * since_id: minimum id
 126 * max_id: maximum id
 127 * getText: Defines the format of the status field. Can be "html" or "plain"
 128 * include_entities: "true" shows entities for pictures and links (Default: false)
 129 * friendica_verbose: "true" enables different error returns (default: "false")
 130
 131 #### Unsupported parameters
 132
 133 * skip_status
 134
 135 ---
 136
 137 ### direct_messages/all (*; AUTH)
 138
 139 #### Parameters
 140
 141 * count: Items per page (default: 20)
 142 * page: page number
 143 * since_id: minimum id
 144 * max_id: maximum id
 145 * getText: Defines the format of the status field. Can be "html" or "plain"
 146 * friendica_verbose: "true" enables different error returns (default: "false")
 147
 148 ---
 149
 150 ### direct_messages/conversation (*; AUTH)
 151
 152 Shows all direct messages of a conversation
 153
 154 #### Parameters
 155
 156 * count: Items per page (default: 20)
 157 * page: page number
 158 * since_id: minimum id
 159 * max_id: maximum id
 160 * getText: Defines the format of the status field. Can be "html" or "plain"
 161 * uri: URI of the conversation
 162 * friendica_verbose: "true" enables different error returns (default: "false")
 163
 164 ---
 165
 166 ### direct_messages/sent (*; AUTH)
 167
 168 #### Parameters
 169
 170 * count: Items per page (default: 20)
 171 * page: page number
 172 * since_id: minimum id
 173 * max_id: maximum id
 174 * getText: Defines the format of the status field. Can be "html" or "plain"
 175 * include_entities: "true" shows entities for pictures and links (Default: false)
 176 * friendica_verbose: "true" enables different error returns (default: "false")
 177
 178 ---
 179
 180 ### direct_messages/new (POST,PUT; AUTH)
 181
 182 #### Parameters
 183
 184 * user_id: id of the user
 185 * screen_name: screen name (for technical reasons, this value is not unique!)
 186 * text: The message
 187 * replyto: ID of the replied direct message
 188 * title: Title of the direct message
 189
 190 ---
 191
 192 ### direct_messages/destroy (POST,DELETE; AUTH)
 193
 194 #### Parameters
 195
 196 * id: id of the message to be deleted
 197 * include_entities: optional, currently not yet implemented
 198 * friendica_parenturi: optional, can be used for increased safety to delete only intended messages
 199 * friendica_verbose: "true" enables different error returns (default: "false")
 200
 201 #### Return values
 202
 203 On success:
 204
 205 * JSON return as defined for Twitter API not yet implemented
 206 * on friendica_verbose=true: JSON return {"result":"ok","message":"message deleted"}
 207
 208 On error:
 209 HTTP 400 BadRequest
 210
 211 * on friendica_verbose=true: different JSON returns {"result":"error","message":"xyz"}
 212
 213 ---
 214
 215 ### externalprofile/show (*)
 216
 217 #### Parameters
 218
 219 * profileurl: profile url
 220
 221 ---
 222
 223 ### favorites (*; AUTH)
 224
 225 #### Parameters
 226
 227 * count: Items per page (default: 20)
 228 * page: page number
 229 * since_id: minimum id
 230 * max_id: maximum id
 231 * include_entities: "true" shows entities for pictures and links (Default: false)
 232
 233 #### Unsupported parameters
 234
 235 * user_id
 236 * screen_name
 237
 238 Favorites aren't displayed to other users, so "user_id" and "screen_name" are unsupported.
 239 Set this values will result in an empty array.
 240
 241 ---
 242
 243 ### favorites/create (POST,PUT; AUTH)
 244
 245 #### Parameters
 246
 247 * id
 248 * include_entities: "true" shows entities for pictures and links (Default: false)
 249
 250 ---
 251
 252 ### favorites/destroy (POST,DELETE; AUTH)
 253
 254 #### Parameters
 255
 256 * id
 257 * include_entities: "true" shows entities for pictures and links (Default: false)
 258
 259 ---
 260
 261 ### followers/ids (*; AUTH)
 262
 263 #### Parameters
 264
 265 * stringify_ids: Send id numbers as text (true) or integers (false)? (default: false)
 266
 267 #### Unsupported parameters
 268
 269 * user_id
 270 * screen_name
 271 * cursor
 272
 273 Friendica doesn't allow showing the followers of other users.
 274
 275 ---
 276
 277 ### friends/ids (*; AUTH)
 278
 279 #### Parameters
 280
 281 * stringify_ids: Send the id numbers as text (true) or integers (false)? (default: false)
 282
 283 #### Unsupported parameters
 284
 285 * user_id
 286 * screen_name
 287 * cursor
 288
 289 Friendica doesn't allow showing the friends of other users.
 290
 291 ---
 292
 293 ### help/test (*)
 294
 295 ---
 296
 297 ### lists/ownerships (*; AUTH)
 298
 299 #### Parameters
 300
 301 * list_id: ID of the list
 302 * count: Items per page
 303 * page: Page number
 304 * since_id: Minimum ID
 305 * max_id: Maximum ID
 306
 307 #### Unsupported parameters
 308
 309 * slug
 310 * owner_screen_name
 311 * owner_id
 312 * include_entities
 313 * include_rts
 314
 315 ---
 316
 317 ### lists/destroy (POST; AUTH)
 318
 319 #### Parameters
 320
 321 * list_id: ID of the list
 322
 323 #### Unsupported parameters
 324
 325 * owner_screen_name
 326 * owner_id
 327 * slug
 328
 329 ---
 330
 331 ### lists/create (POST; AUTH)
 332
 333 #### Parameters
 334
 335 * name: name of the list
 336
 337 #### Unsupported parameters
 338
 339 * mode
 340 * description
 341
 342 ---
 343
 344 ### lists/update (POST; AUTH)
 345
 346 #### Parameters
 347
 348 * list_id: ID of the list
 349 * name: name of the list
 350
 351 #### Unsupported parameters
 352
 353 * slug
 354 * name
 355 * mode
 356 * description
 357 * owner_screen_name
 358 * owner_id
 359
 360 ---
 361
 362 ### lists/statuses (*; AUTH)
 363
 364 #### Parameters
 365
 366 * user_id: ID of the user for whom to return results.
 367
 368 #### Unsupported parameters
 369
 370 * screen_name
 371 * count
 372 * cursor
 373
 374 ---
 375
 376 ### media/upload (POST,PUT; AUTH)
 377
 378 #### Parameters
 379
 380 * media: image data
 381
 382 #### Return values
 383
 384 Object of:
 385
 386 * media_id: a media identifier (integer)
 387 * media_id_string: a media identifier (string)
 388 * size: size in byte
 389 * image.w: image width
 390 * image.h: image height
 391 * image.image_type: image mime type
 392 * image.friendica_preview_url: image preview url
 393
 394 ---
 395
 396 ### oauth/request_token (*)
 397
 398 #### Parameters
 399
 400 * oauth_callback
 401
 402 #### Unsupported parameters
 403
 404 * x_auth_access_type
 405
 406 ---
 407
 408 ### oauth/access_token (*)
 409
 410 #### Parameters
 411
 412 * oauth_verifier
 413
 414 #### Unsupported parameters
 415
 416 * x_auth_password
 417 * x_auth_username
 418 * x_auth_mode
 419
 420 ---
 421
 422 ### statuses/destroy (POST,DELETE; AUTH)
 423
 424 #### Parameters
 425
 426 * id: message number
 427 * include_entities: "true" shows entities for pictures and links (Default: false)
 428
 429 #### Unsupported parameters
 430
 431 * trim_user
 432
 433 ---
 434
 435 ### statuses/followers (*; AUTH)
 436
 437 #### Parameters
 438
 439 * include_entities: "true" shows entities for pictures and links (Default: false)
 440
 441 ---
 442
 443 ### statuses/friends (*; AUTH)
 444
 445 #### Parameters
 446
 447 * include_entities: "true" shows entities for pictures and links (Default: false)
 448 * count: how many items should be shown (Default: 20)
 449
 450 ---
 451
 452 ### blocks/list (*; AUTH)
 453
 454 #### Parameters
 455
 456 * include_entities: "true" shows entities for pictures and links (Default: false)
 457 * count: Items per page (default: 20).
 458 * page: page number
 459
 460 #### Unsupported parameters
 461
 462 * cursor
 463 * skip_status
 464
 465 ---
 466
 467 ### statuses/friends_timeline (*; AUTH)
 468
 469 #### Parameters
 470
 471 * count: Items per page (default: 20)
 472 * page: page number
 473 * since_id: minimum id
 474 * max_id: maximum id
 475 * exclude_replies: don't show replies (default: false)
 476 * conversation_id: Shows all statuses of a given conversation.
 477 * include_entities: "true" shows entities for pictures and links (Default: false)
 478
 479 #### Unsupported parameters
 480
 481 * include_rts
 482 * trim_user
 483 * contributor_details
 484
 485 ---
 486
 487 ### statuses/home_timeline (*; AUTH)
 488
 489 #### Parameters
 490
 491 * count: Items per page (default: 20)
 492 * page: page number
 493 * since_id: minimum id
 494 * max_id: maximum id
 495 * exclude_replies: don't show replies (default: false)
 496 * conversation_id: Shows all statuses of a given conversation.
 497 * include_entities: "true" shows entities for pictures and links (Default: false)
 498
 499 #### Unsupported parameters
 500
 501 * include_rts
 502 * trim_user
 503 * contributor_details
 504
 505 ---
 506
 507 ### statuses/mentions (*; AUTH)
 508
 509 #### Parameters
 510
 511 * count: Items per page (default: 20)
 512 * page: page number
 513 * since_id: minimum id
 514 * max_id: maximum id
 515 * include_entities: "true" shows entities for pictures and links (Default: false)
 516
 517 #### Unsupported parameters
 518
 519 * include_rts
 520 * trim_user
 521 * contributor_details
 522
 523 ---
 524
 525 ### statuses/public_timeline (*; AUTH)
 526
 527 #### Parameters
 528
 529 * count: Items per page (default: 20)
 530 * page: page number
 531 * since_id: minimum id
 532 * max_id: maximum id
 533 * exclude_replies: don't show replies (default: false)
 534 * conversation_id: Shows all statuses of a given conversation.
 535 * include_entities: "true" shows entities for pictures and links (Default: false)
 536
 537 #### Unsupported parameters
 538
 539 * trim_user
 540
 541 ---
 542
 543 ### statuses/networkpublic_timeline (*; AUTH)
 544
 545 #### Parameters
 546
 547 * count: Items per page (default: 20)
 548 * page: page number
 549 * since_id: minimum id
 550 * max_id: maximum id
 551 * include_entities: "true" shows entities for pictures and links (Default: false)
 552
 553 ---
 554
 555 ### statuses/replies (*; AUTH)
 556
 557 #### Parameters
 558
 559 * count: Items per page (default: 20)
 560 * page: page number
 561 * since_id: minimum id
 562 * max_id: maximum id
 563 * include_entities: "true" shows entities for pictures and links (Default: false)
 564
 565 #### Unsupported parameters
 566
 567 * include_rts
 568 * trim_user
 569 * contributor_details
 570
 571 ---
 572
 573 ### statuses/retweet (POST,PUT; AUTH)
 574
 575 #### Parameters
 576
 577 * id: message number
 578 * include_entities: "true" shows entities for pictures and links (Default: false)
 579
 580 #### Unsupported parameters
 581
 582 * trim_user
 583
 584 ---
 585
 586 ### statuses/show (*; AUTH)
 587
 588 #### Parameters
 589
 590 * id: message number
 591 * conversation: if set to "1" show all messages of the conversation with the given id
 592 * include_entities: "true" shows entities for pictures and links (Default: false)
 593
 594 #### Unsupported parameters
 595
 596 * include_my_retweet
 597 * trim_user
 598
 599 ---
 600
 601 ### statuses/update, statuses/update_with_media
 602
 603 #### Parameters
 604
 605 * title: Title of the status
 606 * status: Status in text format
 607 * htmlstatus: Status in HTML format
 608 * in_reply_to_status_id
 609 * lat: latitude
 610 * long: longitude
 611 * media: image data
 612 * source: Application name
 613 * group_allow
 614 * contact_allow
 615 * group_deny
 616 * contact_deny
 617 * network
 618 * include_entities: "true" shows entities for pictures and links (Default: false)
 619 * media_ids: (By now only a single value, no array)
 620
 621 #### Unsupported parameters
 622
 623 * trim_user
 624 * place_id
 625 * display_coordinates
 626
 627 ---
 628
 629 ### statuses/user_timeline (*; AUTH)
 630
 631 #### Parameters
 632
 633 * user_id: id of the user
 634 * screen_name: screen name (for technical reasons, this value is not unique!)
 635 * count: Items per page (default: 20)
 636 * page: page number
 637 * since_id: minimum id
 638 * max_id: maximum id
 639 * exclude_replies: don't show replies (default: false)
 640 * conversation_id: Shows all statuses of a given conversation.
 641 * include_entities: "true" shows entities for pictures and links (Default: false)
 642
 643 #### Unsupported parameters
 644
 645 * include_rts
 646 * trim_user
 647 * contributor_details
 648
 649 ---
 650
 651 ### Return values for statuses/* api calls
 652
 653 Returned status object is conform to GNU Social/Twitter api.
 654
 655 Friendica adds some addictional fields:
 656
 657 - author: a user object, it's the author of the item. In case of a reshare for legacy reasons the "user" field doesn't show the real author. This field always contains the real author of a post.
 658 - owner: a user object, it's the owner of the item.
 659 - private: boolean, true if the item is marked as private
 660 - activities: map with activities related to the item. Every activity is a list of user objects.
 661 - comments: comment numbers
 662
 663 This properties are prefixed with "friendica_" in JSON responses and namespaced under "http://friendi.ca/schema/api/1/" in XML responses
 664
 665 JSON:
 666
 667 ```json
 668 [
 669         {
 670                 // ...
 671                 'friendica_author' : {
 672                         // user object
 673                 },
 674                 'friendica_owner' : {
 675                         // user object
 676                 },
 677                 'friendica_private' : true,
 678                 'friendica_activities': {
 679                         'like': [
 680                                 {
 681                                         // user object
 682                                 },
 683                                 // ...
 684                         ],
 685                         'dislike': [],
 686                         'attendyes': [],
 687                         'attendno': [],
 688                         'attendmaybe': []
 689                 },
 690                 'friendica_comments': 12
 691         },
 692         // ...
 693 ]
 694 ```
 695
 696 XML:
 697
 698 ```xml
 699 <statuses xmlns="http://api.twitter.com" xmlns:statusnet="http://status.net/schema/api/1/" xmlns:friendica="http://friendi.ca/schema/api/1/" xmlns:georss="http://www.georss.org/georss">
 700   <status>
 701         <!-- ... -->
 702         <friendica:owner><!-- user object --></friendica:owner>
 703         <friendica:private>true</friendica:private>
 704         <friendica:activities>
 705                 <friendica:like>
 706                 <user>
 707                         <!-- user object -->
 708                 </user>
 709                 <!-- ... --->
 710                 </friendica:like>
 711                 <friendica:dislike/>
 712                 <friendica:attendyes/>
 713                 <friendica:attendno/>
 714                 <friendica:attendmaybe/>
 715         </friendica:activities>
 716         <friendica:comments>21</friendica:comments>
 717         </status>
 718         <!-- ... -->
 719 </statuses>
 720 ```
 721
 722
 723 ---
 724
 725 ### statusnet/config (*)
 726
 727 ---
 728
 729 ### statusnet/conversation (*; AUTH)
 730
 731 It shows all direct answers (excluding the original post) to a given id.
 732
 733 #### Parameter
 734
 735 * id: id of the post
 736 * count: Items per page (default: 20)
 737 * page: page number
 738 * since_id: minimum id
 739 * max_id: maximum id
 740 * include_entities: "true" shows entities for pictures and links (Default: false)
 741
 742 ---
 743
 744 ### statusnet/version (*)
 745
 746 #### Unsupported parameters
 747
 748 * user_id
 749 * screen_name
 750 * cursor
 751
 752 Friendica doesn't allow showing followers of other users.
 753
 754 ---
 755
 756 ### search (*; AUTH)
 757
 758 #### Parameters
 759
 760 * q: search query
 761 * page: the page number (starting at 1) to return
 762 * rpp: the number of statuses to return per page
 763 * count: alias for the rpp parameter
 764 * since_id: returns statuses with ids greater than the given id
 765 * max_id: returns statuses with ids lower or equal to the given id
 766 * exclude_replies: don't show replies (default: false)
 767
 768 #### Unsupported parameters
 769
 770 * geocode
 771 * lang
 772 * locale
 773 * result_type
 774 * until
 775 * include_entities
 776
 777 ---
 778
 779 ### search/tweets (*; AUTH)
 780
 781 This is an alias for `search`.
 782
 783 ---
 784
 785 ### saved_searches/list (*; AUTH)
 786
 787 This call does not have any parameter.
 788
 789 ---
 790
 791 ### users/search (*)
 792
 793 #### Parameters
 794
 795 * q: name of the user
 796
 797 #### Unsupported parameters
 798
 799 * page
 800 * count
 801 * include_entities
 802
 803 ---
 804
 805 ### users/show (*)
 806
 807 #### Parameters
 808
 809 * user_id: id of the user
 810 * screen_name: screen name (for technical reasons, this value is not unique!)
 811 * include_entities: "true" shows entities for pictures and links (Default: false)
 812
 813 #### Unsupported parameters
 814
 815 * user_id
 816 * screen_name
 817 * cursor
 818
 819 Friendica doesn't allow showing friends of other users.
 820
 821 ---
 822
 823 ### users/lookup (*; AUTH)
 824
 825 #### Parameters
 826
 827 * user_id: list of ids to lookup
 828
 829 #### Unsupported parameters
 830
 831 * screen_name
 832 * include_entities
 833
 834 ---
 835
 836 ### account/update_profile_image (POST; AUTH)
 837
 838 #### Parameters
 839
 840 * image: image data as base64 (Twitter has a limit of 700kb, Friendica allows more)
 841 * profile_id (optional): id of the profile for which the image should be used, default is changing the default profile
 842
 843 uploads a new profile image (scales 4-6) to database, changes default or specified profile to the new photo
 844
 845 #### Return values
 846
 847 On success:
 848
 849 * JSON return: returns the updated user details (see account/verify_credentials)
 850
 851 On error:
 852
 853 * 403 FORBIDDEN: if not authenticated
 854 * 400 BADREQUEST: "no media data submitted", "profile_id not available"
 855 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
 856                         "image size exceeds Friendica Config setting (uploaded size: x)",
 857                         "unable to process image data",
 858                         "image upload failed"
 859
 860 ---
 861
 862 ### account/update_profile (POST; AUTH)
 863
 864 #### Parameters
 865
 866 * name (optional): full name of the user
 867 * description (optional): a description of the user
 868
 869 #### Unsupported parameters
 870
 871 * url
 872 * location
 873 * profile_link_color
 874 * include_entities
 875 * skip_status
 876
 877 ---
 878
 879 ### friendships/incoming (*; AUTH)
 880
 881 #### Unsupported parameters
 882
 883 * cursor
 884 * stringify_ids
 885
 886 ## Implemented API calls (not compatible with other APIs)
 887
 888 ---
 889
 890 ### friendica/activity/[verb]
 891
 892 #### parameters
 893
 894 * id: item id
 895
 896 Add or remove an activity from an item.
 897 'verb' can be one of:
 898
 899 * like
 900 * dislike
 901 * attendyes
 902 * attendno
 903 * attendmaybe
 904
 905 To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"
 906 Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".
 907 Attend verbs should be used only with event-related items (there is no check at the moment)
 908
 909 #### Return values
 910
 911 On success:
 912 json:
 913
 914 ```"ok"```
 915
 916 xml:
 917
 918 ```<ok>true</ok>```
 919
 920 On error:
 921 HTTP 400 BadRequest
 922
 923 ---
 924
 925 ### friendica/group_show (*; AUTH)
 926
 927 Return all or a specified group of the user with the containing contacts as array.
 928
 929 #### Parameters
 930
 931 * gid: optional, if not given, API returns all groups of the user
 932
 933 #### Return values
 934
 935 Array of:
 936
 937 * name: name of the group
 938 * gid: id of the group
 939 * user: array of group members (return from api_get_user() function for each member)
 940
 941 ---
 942
 943 ### friendica/group_delete (POST,DELETE; AUTH)
 944
 945 delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted.
 946
 947 #### Parameters
 948
 949 * gid: id of the group to be deleted
 950 * name: name of the group to be deleted
 951
 952 #### Return values
 953
 954 Array of:
 955
 956 * success: true if successfully deleted
 957 * gid: gid of the deleted group
 958 * name: name of the deleted group
 959 * status: „deleted“ if successfully deleted
 960 * wrong users: empty array
 961
 962 ---
 963
 964 ### friendica/group_create (POST,PUT; AUTH)
 965
 966 Create the group with the posted array of contacts as members.
 967
 968 #### Parameters
 969
 970 * name: name of the group to be created
 971
 972 #### POST data
 973
 974 JSON data as Array like the result of "users/group_show":
 975
 976 * gid
 977 * name
 978 * array of users
 979
 980 #### Return values
 981
 982 Array of:
 983
 984 * success: true if successfully created or reactivated
 985 * gid: gid of the created group
 986 * name: name of the created group
 987 * status: „missing user“ | „reactivated“ | „ok“
 988 * wrong users: array of users, which were not available in the contact table
 989
 990 ---
 991
 992 ### friendica/group_update (POST)
 993
 994 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).
 995
 996 #### Parameters
 997
 998 * gid: id of the group to be changed
 999 * name: name of the group to be changed
1000
1001 #### POST data
1002
1003 JSON data as array like the result of „users/group_show“:
1004
1005 * gid
1006 * name
1007 * array of users
1008
1009 #### Return values
1010
1011 Array of:
1012
1013 * success: true if successfully updated
1014 * gid: gid of the changed group
1015 * name: name of the changed group
1016 * status: „missing user“ | „ok“
1017 * wrong users: array of users, which were not available in the contact table
1018
1019 ---
1020
1021 ### friendica/notifications (GET)
1022
1023 Return last 50 notification for current user, ordered by date with unseen item on top
1024
1025 #### Parameters
1026
1027 none
1028
1029 #### Return values
1030
1031 Array of:
1032
1033 * id: id of the note
1034 * type: type of notification as int (see NOTIFY_* constants in boot.php)
1035 * name: full name of the contact subject of the note
1036 * url: contact's profile url
1037 * photo: contact's profile photo
1038 * date: datetime string of the note
1039 * timestamp: timestamp of the node
1040 * date_rel: relative date of the note (eg. "1 hour ago")
1041 * msg: note message in bbcode
1042 * msg_html: note message in html
1043 * msg_plain: note message in plain text
1044 * link: link to note
1045 * seen: seen state: 0 or 1
1046
1047 ---
1048
1049 ### friendica/notifications/seen (POST)
1050
1051 Set note as seen, returns item object if possible
1052
1053 #### Parameters
1054
1055 id: id of the note to set seen
1056
1057 #### Return values
1058
1059 If the note is linked to an item, the item is returned, just like one of the "statuses/*_timeline" api.
1060
1061 If the note is not linked to an item, a success status is returned:
1062
1063 * `success` (json) | `<status>success</status>` (xml)
1064
1065 ---
1066
1067 ### friendica/photo (*; AUTH)
1068
1069 #### Parameters
1070
1071 * photo_id: Resource id of a photo.
1072 * scale: (optional) scale value of the photo
1073
1074 Returns data of a picture with the given resource.
1075 If 'scale' isn't provided, returned data include full url to each scale of the photo.
1076 If 'scale' is set, returned data include image data base64 encoded.
1077
1078 possibile scale value are:
1079
1080 * 0: original or max size by server settings
1081 * 1: image with or height at <= 640
1082 * 2: image with or height at <= 320
1083 * 3: thumbnail 160x160
1084 * 4: Profile image at 300x300
1085 * 5: Profile image at 80x80
1086 * 6: Profile image at 48x48
1087
1088 An image used as profile image has only scale 4-6, other images only 0-3
1089
1090 #### Return values
1091
1092 json:
1093
1094 ```json
1095         {
1096                 "id": "photo id"
1097                 "created": "date(YYYY-MM-DD HH:MM:SS)",
1098                 "edited": "date(YYYY-MM-DD HH:MM:SS)",
1099                 "title": "photo title",
1100                 "desc": "photo description",
1101                 "album": "album name",
1102                 "filename": "original file name",
1103                 "type": "mime type",
1104                 "height": "number",
1105                 "width": "number",
1106                 "profile": "1 if is profile photo",
1107                 "link": {
1108                         "<scale>": "url to image"
1109                         ...
1110                 },
1111                 // if 'scale' is set
1112                 "datasize": "size in byte",
1113                 "data": "base64 encoded image data"
1114         }
1115 ```
1116
1117 xml:
1118
1119 ```xml
1120         <photo>
1121                 <id>photo id</id>
1122                 <created>date(YYYY-MM-DD HH:MM:SS)</created>
1123                 <edited>date(YYYY-MM-DD HH:MM:SS)</edited>
1124                 <title>photo title</title>
1125                 <desc>photo description</desc>
1126                 <album>album name</album>
1127                 <filename>original file name</filename>
1128                 <type>mime type</type>
1129                 <height>number</height>
1130                 <width>number</width>
1131                 <profile>1 if is profile photo</profile>
1132                 <links type="array">
1133                 <link type="mime type" scale="scale number" href="image url"/>
1134                         ...
1135                 </links>
1136         </photo>
1137 ```
1138
1139 ---
1140
1141 ### friendica/photos/list (*; AUTH)
1142
1143 Returns a list of all photo resources of the logged in user.
1144
1145 #### Return values
1146
1147 json:
1148
1149 ```json
1150         [
1151                 {
1152                         id: "resource_id",
1153                         album: "album name",
1154                         filename: "original file name",
1155                         type: "image mime type",
1156                         thumb: "url to thumb sized image"
1157                 },
1158                 ...
1159         ]
1160 ```
1161
1162 xml:
1163
1164 ```xml
1165         <photos type="array">
1166                 <photo id="resource_id"
1167                 album="album name"
1168                 filename="original file name"
1169                 type="image mime type">
1170                         "url to thumb sized image"
1171                 </photo>
1172                 ...
1173         </photos>
1174 ```
1175
1176 ---
1177
1178 ### friendica/photoalbum/delete (POST,DELETE; AUTH)
1179
1180 #### Parameters
1181
1182 * album: name of the album to be deleted
1183
1184 deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this
1185
1186 #### Return values
1187
1188 On success:
1189
1190 * JSON return {"result":"deleted","message":"album 'xyz' with all containing photos has been deleted."}
1191
1192 On error:
1193
1194 * 403 FORBIDDEN: if not authenticated
1195 * 400 BADREQUEST: "no albumname specified", "album not available"
1196 * 500 INTERNALSERVERERROR: "problem with deleting item occured", "unknown error - deleting from database failed"
1197
1198 ---
1199
1200 ### friendica/photoalbum/update (POST,PUT; AUTH)
1201
1202 #### Parameters
1203
1204 * album: name of the album to be updated
1205 * album_new: new name of the album
1206
1207 changes the album name to album_new for all photos in album
1208
1209 #### Return values
1210
1211 On success:
1212
1213 * JSON return {"result":"updated","message":"album 'abc' with all containing photos has been renamed to 'xyz'."}
1214
1215 On error:
1216
1217 * 403 FORBIDDEN: if not authenticated
1218 * 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available"
1219 * 500 INTERNALSERVERERROR: "unknown error - updating in database failed"
1220
1221 ---
1222
1223 ### friendica/photo/create (POST; AUTH)
1224
1225 ### friendica/photo/update (POST; AUTH)
1226
1227 #### Parameters
1228
1229 * photo_id (optional): if specified the photo with this id will be updated
1230 * media (optional): image data as base64, only optional if photo_id is specified (new upload must have media)
1231 * desc (optional): description for the photo, updated when photo_id is specified
1232 * album: name of the album to be deleted (always necessary)
1233 * album_new (optional): can be used to change the album of a single photo if photo_id is specified
1234 * 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;
1235                         on update: keys need to be present with empty values for changing a private photo to public
1236
1237 both calls point to one function for creating AND updating photos.
1238 Saves data for the scales 0-2 to database (see above for scale description).
1239 Call adds non-visible entries to items table to enable authenticated contacts to comment/like the photo.
1240 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.
1241 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.
1242
1243 #### Return values
1244
1245 On success:
1246
1247 * new photo uploaded: JSON return with photo data (see friendica/photo)
1248 * photo updated - changed photo data: JSON return with photo data (see friendica/photo)
1249 * photo updated - changed info: JSON return {"result":"updated","message":"Image id 'xyz' has been updated."}
1250 * photo updated - nothing changed: JSON return {"result":"cancelled","message":"Nothing to update for image id 'xyz'."}
1251
1252 On error:
1253
1254 * 403 FORBIDDEN: if not authenticated
1255 * 400 BADREQUEST: "no albumname specified", "no media data submitted", "photo not available", "acl data invalid"
1256 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
1257                         "image size exceeds Friendica Config setting (uploaded size: x)",
1258                         "unable to process image data",
1259                         "image upload failed",
1260                         "unknown error - uploading photo failed, see Friendica log for more information",
1261                         "unknown error - update photo entry in database failed",
1262                         "unknown error - this error on uploading or updating a photo should never happen"
1263
1264 ---
1265
1266 ### friendica/photo/delete (DELETE; AUTH)
1267
1268 #### Parameters
1269
1270 * photo_id: id of the photo to be deleted
1271
1272 deletes a single image with the specified id, is not reversible -> ensure that client is asking user for being sure to do this
1273 Sets item table entries for this photo to deleted = 1
1274
1275 #### Return values
1276
1277 On success:
1278
1279 * JSON return {"result":"deleted","message":"photo with id 'xyz' has been deleted from server."}
1280
1281 On error:
1282
1283 * 403 FORBIDDEN: if not authenticated
1284 * 400 BADREQUEST: "no photo_id specified", "photo not available"
1285 * 500 INTERNALSERVERERROR: "unknown error on deleting photo", "problem with deleting items occurred"
1286
1287 ---
1288
1289 ### friendica/direct_messages_setseen (GET; AUTH)
1290
1291 #### Parameters
1292
1293 * id: id of the message to be updated as seen
1294
1295 #### Return values
1296
1297 On success:
1298
1299 * JSON return {"result":"ok","message":"message set to seen"}
1300
1301 On error:
1302
1303 * different JSON returns {"result":"error","message":"xyz"}
1304
1305 ---
1306
1307 ### friendica/direct_messages_search (GET; AUTH)
1308
1309 #### Parameters
1310
1311 * searchstring: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored)
1312
1313 #### Return values
1314
1315 Returns only tested with JSON, XML might work as well.
1316
1317 On success:
1318
1319 * JSON return {"success":"true","search_results": array of found messages}
1320 * JSOn return {"success":"false","search_results":"nothing found"}
1321
1322 On error:
1323
1324 * different JSON returns {"result":"error","message":"searchstring not specified"}
1325
1326 ---
1327
1328 ### friendica/profile/show (GET; AUTH)
1329
1330 show data of all profiles or a single profile of the authenticated user
1331
1332 #### Parameters
1333
1334 * profile_id: id of the profile to be returned (optional, if omitted all profiles are returned by default)
1335
1336 #### Return values
1337
1338 On success: Array of:
1339
1340 * multi_profiles: true if user has activated multi_profiles
1341 * global_dir: URL of the global directory set in server settings
1342 * friendica_owner: user data of the authenticated user
1343 * profiles: array of the profile data
1344
1345 On error:
1346 HTTP 403 Forbidden: when no authentication was provided
1347 HTTP 400 Bad Request: if given profile_id is not in the database or is not assigned to the authenticated user
1348
1349 General description of profile data in API returns:
1350
1351 * profile_id
1352 * profile_name
1353 * is_default: true if this is the public profile
1354 * hide_friends: true if friends are hidden
1355 * profile_photo
1356 * profile_thumb
1357 * publish: true if published on the server's local directory
1358 * net_publish: true if published to global_dir
1359 * description ... homepage: different data fields from 'profile' table in database
1360 * users: array with the users allowed to view this profile (empty if is_default=true)
1361
1362 ---
1363
1364 ## Not Implemented API calls
1365
1366 The following API calls are implemented in GNU Social but not in Friendica: (incomplete)
1367
1368 * statuses/retweets_of_me
1369 * friendships/create
1370 * friendships/destroy
1371 * friendships/exists
1372 * friendships/show
1373 * account/update_profile_background_image
1374 * blocks/create
1375 * blocks/destroy
1376
1377 The following API calls from the Twitter API are not implemented in either Friendica or GNU Social:
1378
1379 * statuses/mentions_timeline
1380 * statuses/retweets/:id
1381 * statuses/oembed
1382 * statuses/retweeters/ids
1383 * statuses/lookup
1384 * direct_messages/show
1385 * friendships/no_retweets/ids
1386 * friendships/outgoing
1387 * friendships/update
1388 * friends/list
1389 * friendships/lookup
1390 * account/settings
1391 * account/update_delivery_device
1392 * blocks/ids
1393 * users/show
1394 * users/search
1395 * account/remove_profile_banner
1396 * account/update_profile_banner
1397 * users/profile_banner
1398 * mutes/users/create
1399 * mutes/users/destroy
1400 * mutes/users/ids
1401 * mutes/users/list
1402 * users/suggestions/:slug
1403 * users/suggestions
1404 * users/suggestions/:slug/members
1405 * favorites/list
1406 * lists/list
1407 * lists/members/destroy
1408 * lists/memberships
1409 * lists/subscribers
1410 * lists/subscribers/create
1411 * lists/subscribers/show
1412 * lists/subscribers/destroy
1413 * lists/members/create_all
1414 * lists/members/show
1415 * lists/members
1416 * lists/members/create
1417 * lists/show
1418 * lists/subscriptions
1419 * lists/members/destroy_all
1420 * saved_searches/show/:id
1421 * saved_searches/create
1422 * saved_searches/destroy/:id
1423 * geo/id/:place_id
1424 * geo/reverse_geocode
1425 * geo/search
1426 * geo/place
1427 * trends/place
1428 * trends/available
1429 * help/configuration
1430 * help/languages
1431 * help/privacy
1432 * help/tos
1433 * trends/closest
1434 * users/report_spam
1435
1436 ---
1437
1438 ---
1439
1440 ## Usage Examples
1441
1442 ### BASH / cURL
1443
1444 ```bash
1445 /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"
1446 ```
1447
1448 ### Python
1449
1450 The [RSStoFriendika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python.
1451 The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.
1452
1453 def tweet(server, message, group_allow=None):
1454 url = server + '/api/statuses/update'
1455 urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))
1456
1457 There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.