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