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