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 ### media/metadata/create (POST,PUT; AUTH)
 397
 398 #### Parameters
 399
 400 Parameters are sent as JSON object:
 401
 402 ```
 403 {
 404         "media_id":"1234",
 405         "alt_text": {
 406                 "text":"Here comes the description"
 407         }
 408 }
 409 ```
 410
 411 #### Return values
 412
 413 None
 414
 415 ---
 416
 417 ### oauth/request_token (*)
 418
 419 #### Parameters
 420
 421 * oauth_callback
 422
 423 #### Unsupported parameters
 424
 425 * x_auth_access_type
 426
 427 ---
 428
 429 ### oauth/access_token (*)
 430
 431 #### Parameters
 432
 433 * oauth_verifier
 434
 435 #### Unsupported parameters
 436
 437 * x_auth_password
 438 * x_auth_username
 439 * x_auth_mode
 440
 441 ---
 442
 443 ### statuses/destroy (POST,DELETE; AUTH)
 444
 445 #### Parameters
 446
 447 * id: message number
 448 * include_entities: "true" shows entities for pictures and links (Default: false)
 449
 450 #### Unsupported parameters
 451
 452 * trim_user
 453
 454 ---
 455
 456 ### statuses/followers (*; AUTH)
 457
 458 #### Parameters
 459
 460 * include_entities: "true" shows entities for pictures and links (Default: false)
 461
 462 ---
 463
 464 ### statuses/friends (*; AUTH)
 465
 466 #### Parameters
 467
 468 * include_entities: "true" shows entities for pictures and links (Default: false)
 469 * count: how many items should be shown (Default: 20)
 470
 471 ---
 472
 473 ### blocks/list (*; AUTH)
 474
 475 #### Parameters
 476
 477 * include_entities: "true" shows entities for pictures and links (Default: false)
 478 * count: Items per page (default: 20).
 479 * page: page number
 480
 481 #### Unsupported parameters
 482
 483 * cursor
 484 * skip_status
 485
 486 ---
 487
 488 ### statuses/friends_timeline (*; AUTH)
 489
 490 #### Parameters
 491
 492 * count: Items per page (default: 20)
 493 * page: page number
 494 * since_id: minimum id
 495 * max_id: maximum id
 496 * exclude_replies: don't show replies (default: false)
 497 * conversation_id: Shows all statuses of a given conversation.
 498 * include_entities: "true" shows entities for pictures and links (Default: false)
 499
 500 #### Unsupported parameters
 501
 502 * include_rts
 503 * trim_user
 504 * contributor_details
 505
 506 ---
 507
 508 ### statuses/home_timeline (*; AUTH)
 509
 510 #### Parameters
 511
 512 * count: Items per page (default: 20)
 513 * page: page number
 514 * since_id: minimum id
 515 * max_id: maximum id
 516 * exclude_replies: don't show replies (default: false)
 517 * conversation_id: Shows all statuses of a given conversation.
 518 * include_entities: "true" shows entities for pictures and links (Default: false)
 519
 520 #### Unsupported parameters
 521
 522 * include_rts
 523 * trim_user
 524 * contributor_details
 525
 526 ---
 527
 528 ### statuses/mentions (*; AUTH)
 529
 530 #### Parameters
 531
 532 * count: Items per page (default: 20)
 533 * page: page number
 534 * since_id: minimum id
 535 * max_id: maximum id
 536 * include_entities: "true" shows entities for pictures and links (Default: false)
 537
 538 #### Unsupported parameters
 539
 540 * include_rts
 541 * trim_user
 542 * contributor_details
 543
 544 ---
 545
 546 ### statuses/public_timeline (*; AUTH)
 547
 548 #### Parameters
 549
 550 * count: Items per page (default: 20)
 551 * page: page number
 552 * since_id: minimum id
 553 * max_id: maximum id
 554 * exclude_replies: don't show replies (default: false)
 555 * conversation_id: Shows all statuses of a given conversation.
 556 * include_entities: "true" shows entities for pictures and links (Default: false)
 557
 558 #### Unsupported parameters
 559
 560 * trim_user
 561
 562 ---
 563
 564 ### statuses/networkpublic_timeline (*; AUTH)
 565
 566 #### Parameters
 567
 568 * count: Items per page (default: 20)
 569 * page: page number
 570 * since_id: minimum id
 571 * max_id: maximum id
 572 * include_entities: "true" shows entities for pictures and links (Default: false)
 573
 574 ---
 575
 576 ### statuses/replies (*; AUTH)
 577
 578 #### Parameters
 579
 580 * count: Items per page (default: 20)
 581 * page: page number
 582 * since_id: minimum id
 583 * max_id: maximum id
 584 * include_entities: "true" shows entities for pictures and links (Default: false)
 585
 586 #### Unsupported parameters
 587
 588 * include_rts
 589 * trim_user
 590 * contributor_details
 591
 592 ---
 593
 594 ### statuses/retweet (POST,PUT; AUTH)
 595
 596 #### Parameters
 597
 598 * id: message number
 599 * include_entities: "true" shows entities for pictures and links (Default: false)
 600
 601 #### Unsupported parameters
 602
 603 * trim_user
 604
 605 ---
 606
 607 ### statuses/show (*; AUTH)
 608
 609 #### Parameters
 610
 611 * id: message number
 612 * conversation: if set to "1" show all messages of the conversation with the given id
 613 * include_entities: "true" shows entities for pictures and links (Default: false)
 614
 615 #### Unsupported parameters
 616
 617 * include_my_retweet
 618 * trim_user
 619
 620 ---
 621
 622 ### statuses/update, statuses/update_with_media
 623
 624 #### Parameters
 625
 626 * title: Title of the status
 627 * status: Status in text format
 628 * htmlstatus: Status in HTML format
 629 * in_reply_to_status_id
 630 * lat: latitude
 631 * long: longitude
 632 * media: image data
 633 * source: Application name
 634 * group_allow
 635 * contact_allow
 636 * group_deny
 637 * contact_deny
 638 * network
 639 * include_entities: "true" shows entities for pictures and links (Default: false)
 640 * media_ids: (By now only a single value, no array)
 641
 642 #### Unsupported parameters
 643
 644 * trim_user
 645 * place_id
 646 * display_coordinates
 647
 648 ---
 649
 650 ### statuses/user_timeline (*; AUTH)
 651
 652 #### Parameters
 653
 654 * user_id: id of the user
 655 * screen_name: screen name (for technical reasons, this value is not unique!)
 656 * count: Items per page (default: 20)
 657 * page: page number
 658 * since_id: minimum id
 659 * max_id: maximum id
 660 * exclude_replies: don't show replies (default: false)
 661 * conversation_id: Shows all statuses of a given conversation.
 662 * include_entities: "true" shows entities for pictures and links (Default: false)
 663
 664 #### Unsupported parameters
 665
 666 * include_rts
 667 * trim_user
 668 * contributor_details
 669
 670 ---
 671
 672 ### Return values for statuses/* api calls
 673
 674 Returned status object is conform to GNU Social/Twitter api.
 675
 676 Friendica adds some addictional fields:
 677
 678 - 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.
 679 - owner: a user object, it's the owner of the item.
 680 - private: boolean, true if the item is marked as private
 681 - activities: map with activities related to the item. Every activity is a list of user objects.
 682 - comments: comment numbers
 683
 684 This properties are prefixed with "friendica_" in JSON responses and namespaced under "http://friendi.ca/schema/api/1/" in XML responses
 685
 686 JSON:
 687
 688 ```json
 689 [
 690         {
 691                 // ...
 692                 'friendica_author' : {
 693                         // user object
 694                 },
 695                 'friendica_owner' : {
 696                         // user object
 697                 },
 698                 'friendica_private' : true,
 699                 'friendica_activities': {
 700                         'like': [
 701                                 {
 702                                         // user object
 703                                 },
 704                                 // ...
 705                         ],
 706                         'dislike': [],
 707                         'attendyes': [],
 708                         'attendno': [],
 709                         'attendmaybe': []
 710                 },
 711                 'friendica_comments': 12
 712         },
 713         // ...
 714 ]
 715 ```
 716
 717 XML:
 718
 719 ```xml
 720 <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">
 721   <status>
 722         <!-- ... -->
 723         <friendica:owner><!-- user object --></friendica:owner>
 724         <friendica:private>true</friendica:private>
 725         <friendica:activities>
 726                 <friendica:like>
 727                 <user>
 728                         <!-- user object -->
 729                 </user>
 730                 <!-- ... --->
 731                 </friendica:like>
 732                 <friendica:dislike/>
 733                 <friendica:attendyes/>
 734                 <friendica:attendno/>
 735                 <friendica:attendmaybe/>
 736         </friendica:activities>
 737         <friendica:comments>21</friendica:comments>
 738         </status>
 739         <!-- ... -->
 740 </statuses>
 741 ```
 742
 743
 744 ---
 745
 746 ### statusnet/config (*)
 747
 748 ---
 749
 750 ### statusnet/conversation (*; AUTH)
 751
 752 It shows all direct answers (excluding the original post) to a given id.
 753
 754 #### Parameter
 755
 756 * id: id of the post
 757 * count: Items per page (default: 20)
 758 * page: page number
 759 * since_id: minimum id
 760 * max_id: maximum id
 761 * include_entities: "true" shows entities for pictures and links (Default: false)
 762
 763 ---
 764
 765 ### statusnet/version (*)
 766
 767 #### Unsupported parameters
 768
 769 * user_id
 770 * screen_name
 771 * cursor
 772
 773 Friendica doesn't allow showing followers of other users.
 774
 775 ---
 776
 777 ### search (*; AUTH)
 778
 779 #### Parameters
 780
 781 * q: search query
 782 * page: the page number (starting at 1) to return
 783 * rpp: the number of statuses to return per page
 784 * count: alias for the rpp parameter
 785 * since_id: returns statuses with ids greater than the given id
 786 * max_id: returns statuses with ids lower or equal to the given id
 787 * exclude_replies: don't show replies (default: false)
 788
 789 #### Unsupported parameters
 790
 791 * geocode
 792 * lang
 793 * locale
 794 * result_type
 795 * until
 796 * include_entities
 797
 798 ---
 799
 800 ### search/tweets (*; AUTH)
 801
 802 This is an alias for `search`.
 803
 804 ---
 805
 806 ### saved_searches/list (*; AUTH)
 807
 808 This call does not have any parameter.
 809
 810 ---
 811
 812 ### users/search (*)
 813
 814 #### Parameters
 815
 816 * q: name of the user
 817
 818 #### Unsupported parameters
 819
 820 * page
 821 * count
 822 * include_entities
 823
 824 ---
 825
 826 ### users/show (*)
 827
 828 #### Parameters
 829
 830 * user_id: id of the user
 831 * screen_name: screen name (for technical reasons, this value is not unique!)
 832 * include_entities: "true" shows entities for pictures and links (Default: false)
 833
 834 #### Unsupported parameters
 835
 836 * user_id
 837 * screen_name
 838 * cursor
 839
 840 Friendica doesn't allow showing friends of other users.
 841
 842 ---
 843
 844 ### users/lookup (*; AUTH)
 845
 846 #### Parameters
 847
 848 * user_id: list of ids to lookup
 849
 850 #### Unsupported parameters
 851
 852 * screen_name
 853 * include_entities
 854
 855 ---
 856
 857 ### account/update_profile_image (POST; AUTH)
 858
 859 #### Parameters
 860
 861 * image: image data as base64 (Twitter has a limit of 700kb, Friendica allows more)
 862 * profile_id (optional): id of the profile for which the image should be used, default is changing the default profile
 863
 864 uploads a new profile image (scales 4-6) to database, changes default or specified profile to the new photo
 865
 866 #### Return values
 867
 868 On success:
 869
 870 * JSON return: returns the updated user details (see account/verify_credentials)
 871
 872 On error:
 873
 874 * 403 FORBIDDEN: if not authenticated
 875 * 400 BADREQUEST: "no media data submitted", "profile_id not available"
 876 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
 877                         "image size exceeds Friendica Config setting (uploaded size: x)",
 878                         "unable to process image data",
 879                         "image upload failed"
 880
 881 ---
 882
 883 ### account/update_profile (POST; AUTH)
 884
 885 #### Parameters
 886
 887 * name (optional): full name of the user
 888 * description (optional): a description of the user
 889
 890 #### Unsupported parameters
 891
 892 * url
 893 * location
 894 * profile_link_color
 895 * include_entities
 896 * skip_status
 897
 898 ---
 899
 900 ### friendships/incoming (*; AUTH)
 901
 902 #### Unsupported parameters
 903
 904 * cursor
 905 * stringify_ids
 906
 907 ## Implemented API calls (not compatible with other APIs)
 908
 909 ---
 910
 911 ### friendica/activity/[verb]
 912
 913 #### parameters
 914
 915 * id: item id
 916
 917 Add or remove an activity from an item.
 918 'verb' can be one of:
 919
 920 * like
 921 * dislike
 922 * attendyes
 923 * attendno
 924 * attendmaybe
 925
 926 To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"
 927 Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".
 928 Attend verbs should be used only with event-related items (there is no check at the moment)
 929
 930 #### Return values
 931
 932 On success:
 933 json:
 934
 935 ```"ok"```
 936
 937 xml:
 938
 939 ```<ok>true</ok>```
 940
 941 On error:
 942 HTTP 400 BadRequest
 943
 944 ---
 945
 946 ### friendica/group_show (*; AUTH)
 947
 948 Return all or a specified group of the user with the containing contacts as array.
 949
 950 #### Parameters
 951
 952 * gid: optional, if not given, API returns all groups of the user
 953
 954 #### Return values
 955
 956 Array of:
 957
 958 * name: name of the group
 959 * gid: id of the group
 960 * user: array of group members (return from api_get_user() function for each member)
 961
 962 ---
 963
 964 ### friendica/group_delete (POST,DELETE; AUTH)
 965
 966 delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted.
 967
 968 #### Parameters
 969
 970 * gid: id of the group to be deleted
 971 * name: name of the group to be deleted
 972
 973 #### Return values
 974
 975 Array of:
 976
 977 * success: true if successfully deleted
 978 * gid: gid of the deleted group
 979 * name: name of the deleted group
 980 * status: „deleted“ if successfully deleted
 981 * wrong users: empty array
 982
 983 ---
 984
 985 ### friendica/group_create (POST,PUT; AUTH)
 986
 987 Create the group with the posted array of contacts as members.
 988
 989 #### Parameters
 990
 991 * name: name of the group to be created
 992
 993 #### POST data
 994
 995 JSON data as Array like the result of "users/group_show":
 996
 997 * gid
 998 * name
 999 * array of users
1000
1001 #### Return values
1002
1003 Array of:
1004
1005 * success: true if successfully created or reactivated
1006 * gid: gid of the created group
1007 * name: name of the created group
1008 * status: „missing user“ | „reactivated“ | „ok“
1009 * wrong users: array of users, which were not available in the contact table
1010
1011 ---
1012
1013 ### friendica/group_update (POST)
1014
1015 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).
1016
1017 #### Parameters
1018
1019 * gid: id of the group to be changed
1020 * name: name of the group to be changed
1021
1022 #### POST data
1023
1024 JSON data as array like the result of „users/group_show“:
1025
1026 * gid
1027 * name
1028 * array of users
1029
1030 #### Return values
1031
1032 Array of:
1033
1034 * success: true if successfully updated
1035 * gid: gid of the changed group
1036 * name: name of the changed group
1037 * status: „missing user“ | „ok“
1038 * wrong users: array of users, which were not available in the contact table
1039
1040 ---
1041
1042 ### friendica/notifications (GET)
1043
1044 Return last 50 notification for current user, ordered by date with unseen item on top
1045
1046 #### Parameters
1047
1048 none
1049
1050 #### Return values
1051
1052 Array of:
1053
1054 * id: id of the note
1055 * type: type of notification as int (see NOTIFY_* constants in boot.php)
1056 * name: full name of the contact subject of the note
1057 * url: contact's profile url
1058 * photo: contact's profile photo
1059 * date: datetime string of the note
1060 * timestamp: timestamp of the node
1061 * date_rel: relative date of the note (eg. "1 hour ago")
1062 * msg: note message in bbcode
1063 * msg_html: note message in html
1064 * msg_plain: note message in plain text
1065 * link: link to note
1066 * seen: seen state: 0 or 1
1067
1068 ---
1069
1070 ### friendica/notifications/seen (POST)
1071
1072 Set note as seen, returns item object if possible
1073
1074 #### Parameters
1075
1076 id: id of the note to set seen
1077
1078 #### Return values
1079
1080 If the note is linked to an item, the item is returned, just like one of the "statuses/*_timeline" api.
1081
1082 If the note is not linked to an item, a success status is returned:
1083
1084 * `success` (json) | `<status>success</status>` (xml)
1085
1086 ---
1087
1088 ### friendica/photo (*; AUTH)
1089
1090 #### Parameters
1091
1092 * photo_id: Resource id of a photo.
1093 * scale: (optional) scale value of the photo
1094
1095 Returns data of a picture with the given resource.
1096 If 'scale' isn't provided, returned data include full url to each scale of the photo.
1097 If 'scale' is set, returned data include image data base64 encoded.
1098
1099 possibile scale value are:
1100
1101 * 0: original or max size by server settings
1102 * 1: image with or height at <= 640
1103 * 2: image with or height at <= 320
1104 * 3: thumbnail 160x160
1105 * 4: Profile image at 300x300
1106 * 5: Profile image at 80x80
1107 * 6: Profile image at 48x48
1108
1109 An image used as profile image has only scale 4-6, other images only 0-3
1110
1111 #### Return values
1112
1113 json:
1114
1115 ```json
1116         {
1117                 "id": "photo id"
1118                 "created": "date(YYYY-MM-DD HH:MM:SS)",
1119                 "edited": "date(YYYY-MM-DD HH:MM:SS)",
1120                 "title": "photo title",
1121                 "desc": "photo description",
1122                 "album": "album name",
1123                 "filename": "original file name",
1124                 "type": "mime type",
1125                 "height": "number",
1126                 "width": "number",
1127                 "profile": "1 if is profile photo",
1128                 "link": {
1129                         "<scale>": "url to image"
1130                         ...
1131                 },
1132                 // if 'scale' is set
1133                 "datasize": "size in byte",
1134                 "data": "base64 encoded image data"
1135         }
1136 ```
1137
1138 xml:
1139
1140 ```xml
1141         <photo>
1142                 <id>photo id</id>
1143                 <created>date(YYYY-MM-DD HH:MM:SS)</created>
1144                 <edited>date(YYYY-MM-DD HH:MM:SS)</edited>
1145                 <title>photo title</title>
1146                 <desc>photo description</desc>
1147                 <album>album name</album>
1148                 <filename>original file name</filename>
1149                 <type>mime type</type>
1150                 <height>number</height>
1151                 <width>number</width>
1152                 <profile>1 if is profile photo</profile>
1153                 <links type="array">
1154                 <link type="mime type" scale="scale number" href="image url"/>
1155                         ...
1156                 </links>
1157         </photo>
1158 ```
1159
1160 ---
1161
1162 ### friendica/photos/list (*; AUTH)
1163
1164 Returns a list of all photo resources of the logged in user.
1165
1166 #### Return values
1167
1168 json:
1169
1170 ```json
1171         [
1172                 {
1173                         id: "resource_id",
1174                         album: "album name",
1175                         filename: "original file name",
1176                         type: "image mime type",
1177                         thumb: "url to thumb sized image"
1178                 },
1179                 ...
1180         ]
1181 ```
1182
1183 xml:
1184
1185 ```xml
1186         <photos type="array">
1187                 <photo id="resource_id"
1188                 album="album name"
1189                 filename="original file name"
1190                 type="image mime type">
1191                         "url to thumb sized image"
1192                 </photo>
1193                 ...
1194         </photos>
1195 ```
1196
1197 ---
1198
1199 ### friendica/photoalbum/delete (POST,DELETE; AUTH)
1200
1201 #### Parameters
1202
1203 * album: name of the album to be deleted
1204
1205 deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this
1206
1207 #### Return values
1208
1209 On success:
1210
1211 * JSON return {"result":"deleted","message":"album 'xyz' with all containing photos has been deleted."}
1212
1213 On error:
1214
1215 * 403 FORBIDDEN: if not authenticated
1216 * 400 BADREQUEST: "no albumname specified", "album not available"
1217 * 500 INTERNALSERVERERROR: "problem with deleting item occured", "unknown error - deleting from database failed"
1218
1219 ---
1220
1221 ### friendica/photoalbum/update (POST,PUT; AUTH)
1222
1223 #### Parameters
1224
1225 * album: name of the album to be updated
1226 * album_new: new name of the album
1227
1228 changes the album name to album_new for all photos in album
1229
1230 #### Return values
1231
1232 On success:
1233
1234 * JSON return {"result":"updated","message":"album 'abc' with all containing photos has been renamed to 'xyz'."}
1235
1236 On error:
1237
1238 * 403 FORBIDDEN: if not authenticated
1239 * 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available"
1240 * 500 INTERNALSERVERERROR: "unknown error - updating in database failed"
1241
1242 ---
1243
1244 ### friendica/photo/create (POST; AUTH)
1245
1246 ### friendica/photo/update (POST; AUTH)
1247
1248 #### Parameters
1249
1250 * photo_id (optional): if specified the photo with this id will be updated
1251 * media (optional): image data as base64, only optional if photo_id is specified (new upload must have media)
1252 * desc (optional): description for the photo, updated when photo_id is specified
1253 * album: name of the album to be deleted (always necessary)
1254 * album_new (optional): can be used to change the album of a single photo if photo_id is specified
1255 * 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;
1256                         on update: keys need to be present with empty values for changing a private photo to public
1257
1258 both calls point to one function for creating AND updating photos.
1259 Saves data for the scales 0-2 to database (see above for scale description).
1260 Call adds non-visible entries to items table to enable authenticated contacts to comment/like the photo.
1261 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.
1262 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.
1263
1264 #### Return values
1265
1266 On success:
1267
1268 * new photo uploaded: JSON return with photo data (see friendica/photo)
1269 * photo updated - changed photo data: JSON return with photo data (see friendica/photo)
1270 * photo updated - changed info: JSON return {"result":"updated","message":"Image id 'xyz' has been updated."}
1271 * photo updated - nothing changed: JSON return {"result":"cancelled","message":"Nothing to update for image id 'xyz'."}
1272
1273 On error:
1274
1275 * 403 FORBIDDEN: if not authenticated
1276 * 400 BADREQUEST: "no albumname specified", "no media data submitted", "photo not available", "acl data invalid"
1277 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
1278                         "image size exceeds Friendica Config setting (uploaded size: x)",
1279                         "unable to process image data",
1280                         "image upload failed",
1281                         "unknown error - uploading photo failed, see Friendica log for more information",
1282                         "unknown error - update photo entry in database failed",
1283                         "unknown error - this error on uploading or updating a photo should never happen"
1284
1285 ---
1286
1287 ### friendica/photo/delete (DELETE; AUTH)
1288
1289 #### Parameters
1290
1291 * photo_id: id of the photo to be deleted
1292
1293 deletes a single image with the specified id, is not reversible -> ensure that client is asking user for being sure to do this
1294 Sets item table entries for this photo to deleted = 1
1295
1296 #### Return values
1297
1298 On success:
1299
1300 * JSON return {"result":"deleted","message":"photo with id 'xyz' has been deleted from server."}
1301
1302 On error:
1303
1304 * 403 FORBIDDEN: if not authenticated
1305 * 400 BADREQUEST: "no photo_id specified", "photo not available"
1306 * 500 INTERNALSERVERERROR: "unknown error on deleting photo", "problem with deleting items occurred"
1307
1308 ---
1309
1310 ### friendica/direct_messages_setseen (GET; AUTH)
1311
1312 #### Parameters
1313
1314 * id: id of the message to be updated as seen
1315
1316 #### Return values
1317
1318 On success:
1319
1320 * JSON return {"result":"ok","message":"message set to seen"}
1321
1322 On error:
1323
1324 * different JSON returns {"result":"error","message":"xyz"}
1325
1326 ---
1327
1328 ### friendica/direct_messages_search (GET; AUTH)
1329
1330 #### Parameters
1331
1332 * searchstring: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored)
1333
1334 #### Return values
1335
1336 Returns only tested with JSON, XML might work as well.
1337
1338 On success:
1339
1340 * JSON return {"success":"true","search_results": array of found messages}
1341 * JSOn return {"success":"false","search_results":"nothing found"}
1342
1343 On error:
1344
1345 * different JSON returns {"result":"error","message":"searchstring not specified"}
1346
1347 ---
1348
1349 ### friendica/profile/show (GET; AUTH)
1350
1351 show data of all profiles or a single profile of the authenticated user
1352
1353 #### Parameters
1354
1355 * profile_id: id of the profile to be returned (optional, if omitted all profiles are returned by default)
1356
1357 #### Return values
1358
1359 On success: Array of:
1360
1361 * multi_profiles: true if user has activated multi_profiles
1362 * global_dir: URL of the global directory set in server settings
1363 * friendica_owner: user data of the authenticated user
1364 * profiles: array of the profile data
1365
1366 On error:
1367 HTTP 403 Forbidden: when no authentication was provided
1368 HTTP 400 Bad Request: if given profile_id is not in the database or is not assigned to the authenticated user
1369
1370 General description of profile data in API returns:
1371
1372 * profile_id
1373 * profile_name
1374 * is_default: true if this is the public profile
1375 * hide_friends: true if friends are hidden
1376 * profile_photo
1377 * profile_thumb
1378 * publish: true if published on the server's local directory
1379 * net_publish: true if published to global_dir
1380 * description ... homepage: different data fields from 'profile' table in database
1381 * users: array with the users allowed to view this profile (empty if is_default=true)
1382
1383 ---
1384
1385 ## Not Implemented API calls
1386
1387 The following API calls are implemented in GNU Social but not in Friendica: (incomplete)
1388
1389 * statuses/retweets_of_me
1390 * friendships/create
1391 * friendships/destroy
1392 * friendships/exists
1393 * friendships/show
1394 * account/update_profile_background_image
1395 * blocks/create
1396 * blocks/destroy
1397
1398 The following API calls from the Twitter API are not implemented in either Friendica or GNU Social:
1399
1400 * statuses/mentions_timeline
1401 * statuses/retweets/:id
1402 * statuses/oembed
1403 * statuses/retweeters/ids
1404 * statuses/lookup
1405 * direct_messages/show
1406 * friendships/no_retweets/ids
1407 * friendships/outgoing
1408 * friendships/update
1409 * friends/list
1410 * friendships/lookup
1411 * account/settings
1412 * account/update_delivery_device
1413 * blocks/ids
1414 * users/show
1415 * users/search
1416 * account/remove_profile_banner
1417 * account/update_profile_banner
1418 * users/profile_banner
1419 * mutes/users/create
1420 * mutes/users/destroy
1421 * mutes/users/ids
1422 * mutes/users/list
1423 * users/suggestions/:slug
1424 * users/suggestions
1425 * users/suggestions/:slug/members
1426 * favorites/list
1427 * lists/list
1428 * lists/members/destroy
1429 * lists/memberships
1430 * lists/subscribers
1431 * lists/subscribers/create
1432 * lists/subscribers/show
1433 * lists/subscribers/destroy
1434 * lists/members/create_all
1435 * lists/members/show
1436 * lists/members
1437 * lists/members/create
1438 * lists/show
1439 * lists/subscriptions
1440 * lists/members/destroy_all
1441 * saved_searches/show/:id
1442 * saved_searches/create
1443 * saved_searches/destroy/:id
1444 * geo/id/:place_id
1445 * geo/reverse_geocode
1446 * geo/search
1447 * geo/place
1448 * trends/place
1449 * trends/available
1450 * help/configuration
1451 * help/languages
1452 * help/privacy
1453 * help/tos
1454 * trends/closest
1455 * users/report_spam
1456
1457 ---
1458
1459 ---
1460
1461 ## Usage Examples
1462
1463 ### BASH / cURL
1464
1465 ```bash
1466 /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"
1467 ```
1468
1469 ### Python
1470
1471 The [RSStoFriendika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python.
1472 The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.
1473
1474 def tweet(server, message, group_allow=None):
1475 url = server + '/api/statuses/update'
1476 urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))
1477
1478 There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.