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