doc/api.md

   1 Friendica API
   2 ===
   3
   4 * [Home](help)
   5
   6 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).
   7
   8 Please refer to the linked documentation for further information.
   9
  10 ## Implemented API calls
  11
  12 ### General
  13 #### HTTP Method
  14
  15 API endpoints can restrict the method used to request them.
  16 Using an invalid method results in HTTP error 405 "Method Not Allowed".
  17
  18 In this document, the required method is listed after the endpoint name. "*" means every method can be used.
  19
  20 #### Auth
  21
  22 Friendica supports basic http auth and OAuth 1 to authenticate the user to the api.
  23
  24 OAuth settings can be added by the user in web UI under /settings/oauth/
  25
  26 In this document, endpoints which requires auth are marked with "AUTH" after endpoint name
  27
  28 #### Unsupported parameters
  29 * cursor: Not implemented in GNU Social
  30 * trim_user: Not implemented in GNU Social
  31 * contributor_details: Not implemented in GNU Social
  32 * place_id: Not implemented in GNU Social
  33 * display_coordinates: Not implemented in GNU Social
  34 * include_rts: To-Do
  35 * include_my_retweet: Retweets in Friendica are implemented in a different way
  36
  37 #### Different behaviour
  38 * 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.
  39 * include_entities: Default is "false". If set to "true" then the plain text is formatted so that links are having descriptions.
  40
  41 #### Return values
  42 * cid: Contact id of the user (important for "contact_allow" and "contact_deny")
  43 * network: network of the user
  44
  45 #### Errors
  46 When an error occurs in API call, an HTTP error code is returned, with an error message
  47 Usually:
  48 - 400 Bad Request: if parameters are missing or items can't be found
  49 - 403 Forbidden: if the authenticated user is missing
  50 - 405 Method Not Allowed: if API was called with an invalid method, eg. GET when API require POST
  51 - 501 Not Implemented: if the requested API doesn't exist
  52 - 500 Internal Server Error: on other error conditions
  53
  54 Error body is
  55
  56 json:
  57 ```
  58         {
  59                 "error": "Specific error message",
  60                 "request": "API path requested",
  61                 "code": "HTTP error code"
  62         }
  63 ```
  64
  65 xml:
  66 ```
  67         <status>
  68                 <error>Specific error message</error>
  69                 <request>API path requested</request>
  70                 <code>HTTP error code</code>
  71         </status>
  72 ```
  73
  74 ---
  75 ### account/rate_limit_status (*; AUTH)
  76
  77 ---
  78 ### account/verify_credentials (*; AUTH)
  79 #### Parameters
  80
  81 * skip_status: Don't show the "status" field. (Default: false)
  82 * include_entities: "true" shows entities for pictures and links (Default: false)
  83
  84 ---
  85 ### conversation/show (*; AUTH)
  86 Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
  87
  88 #### Parameter
  89 * id: id of the post
  90 * count: Items per page (default: 20)
  91 * page: page number
  92 * since_id: minimum id
  93 * max_id: maximum id
  94 * include_entities: "true" shows entities for pictures and links (Default: false)
  95
  96 #### Unsupported parameters
  97 * include_rts
  98 * trim_user
  99 * contributor_details
 100
 101 ---
 102 ### direct_messages (*; AUTH)
 103 #### Parameters
 104 * count: Items per page (default: 20)
 105 * page: page number
 106 * since_id: minimum id
 107 * max_id: maximum id
 108 * getText: Defines the format of the status field. Can be "html" or "plain"
 109 * include_entities: "true" shows entities for pictures and links (Default: false)
 110 * friendica_verbose: "true" enables different error returns (default: "false")
 111
 112 #### Unsupported parameters
 113 * skip_status
 114
 115 ---
 116 ### direct_messages/all (*; AUTH)
 117 #### Parameters
 118 * count: Items per page (default: 20)
 119 * page: page number
 120 * since_id: minimum id
 121 * max_id: maximum id
 122 * getText: Defines the format of the status field. Can be "html" or "plain"
 123 * friendica_verbose: "true" enables different error returns (default: "false")
 124
 125 ---
 126 ### direct_messages/conversation (*; AUTH)
 127 Shows all direct messages of a conversation
 128 #### Parameters
 129 * count: Items per page (default: 20)
 130 * page: page number
 131 * since_id: minimum id
 132 * max_id: maximum id
 133 * getText: Defines the format of the status field. Can be "html" or "plain"
 134 * uri: URI of the conversation
 135 * friendica_verbose: "true" enables different error returns (default: "false")
 136
 137 ---
 138 ### direct_messages/sent (*; AUTH)
 139 #### Parameters
 140 * count: Items per page (default: 20)
 141 * page: page number
 142 * since_id: minimum id
 143 * max_id: maximum id
 144 * getText: Defines the format of the status field. Can be "html" or "plain"
 145 * include_entities: "true" shows entities for pictures and links (Default: false)
 146 * friendica_verbose: "true" enables different error returns (default: "false")
 147
 148 ---
 149 ### direct_messages/new (POST,PUT; AUTH)
 150 #### Parameters
 151 * user_id: id of the user
 152 * screen_name: screen name (for technical reasons, this value is not unique!)
 153 * text: The message
 154 * replyto: ID of the replied direct message
 155 * title: Title of the direct message
 156
 157 ---
 158 ### direct_messages/destroy (POST,DELETE; AUTH)
 159 #### Parameters
 160 * id: id of the message to be deleted
 161 * include_entities: optional, currently not yet implemented
 162 * friendica_parenturi: optional, can be used for increased safety to delete only intended messages
 163 * friendica_verbose: "true" enables different error returns (default: "false")
 164
 165 #### Return values
 166
 167 On success:
 168 * JSON return as defined for Twitter API not yet implemented
 169 * on friendica_verbose=true: JSON return {"result":"ok","message":"message deleted"}
 170
 171 On error:
 172 HTTP 400 BadRequest
 173 * on friendica_verbose=true: different JSON returns {"result":"error","message":"xyz"}
 174
 175 ---
 176 ### externalprofile/show (*)
 177 #### Parameters
 178 * profileurl: profile url
 179
 180 ---
 181 ### favorites (*; AUTH)
 182 #### Parameters
 183 * count: Items per page (default: 20)
 184 * page: page number
 185 * since_id: minimum id
 186 * max_id: maximum id
 187 * include_entities: "true" shows entities for pictures and links (Default: false)
 188
 189 #### Unsupported parameters
 190 * user_id
 191 * screen_name
 192
 193 Favorites aren't displayed to other users, so "user_id" and "screen_name" are unsupported.
 194 Set this values will result in an empty array.
 195
 196 ---
 197 ### favorites/create (POST,PUT; AUTH)
 198 #### Parameters
 199 * id
 200 * include_entities: "true" shows entities for pictures and links (Default: false)
 201
 202 ---
 203 ### favorites/destroy (POST,DELETE; AUTH)
 204 #### Parameters
 205 * id
 206 * include_entities: "true" shows entities for pictures and links (Default: false)
 207
 208 ---
 209 ### followers/ids (*; AUTH)
 210 #### Parameters
 211 * stringify_ids: Send id numbers as text (true) or integers (false)? (default: false)
 212
 213 #### Unsupported parameters
 214 * user_id
 215 * screen_name
 216 * cursor
 217
 218 Friendica doesn't allow showing the followers of other users.
 219
 220 ---
 221 ### friends/ids (*; AUTH)
 222 #### Parameters
 223 * stringify_ids: Send the id numbers as text (true) or integers (false)? (default: false)
 224
 225 #### Unsupported parameters
 226 * user_id
 227 * screen_name
 228 * cursor
 229
 230 Friendica doesn't allow showing the friends of other users.
 231
 232 ---
 233 ### help/test (*)
 234
 235 ---
 236 ### media/upload (POST,PUT; AUTH)
 237 #### Parameters
 238 * media: image data
 239
 240 ---
 241 ### oauth/request_token (*)
 242 #### Parameters
 243 * oauth_callback
 244
 245 #### Unsupported parameters
 246 * x_auth_access_type
 247
 248 ---
 249 ### oauth/access_token (*)
 250 #### Parameters
 251 * oauth_verifier
 252
 253 #### Unsupported parameters
 254 * x_auth_password
 255 * x_auth_username
 256 * x_auth_mode
 257
 258 ---
 259 ### statuses/destroy (POST,DELETE; AUTH)
 260 #### Parameters
 261 * id: message number
 262 * include_entities: "true" shows entities for pictures and links (Default: false)
 263
 264 #### Unsupported parameters
 265 * trim_user
 266
 267 ---
 268 ### statuses/followers (*; AUTH)
 269
 270 #### Parameters
 271
 272 * include_entities: "true" shows entities for pictures and links (Default: false)
 273
 274 ---
 275 ### statuses/friends (*; AUTH)
 276
 277 #### Parameters
 278
 279 * include_entities: "true" shows entities for pictures and links (Default: false)
 280
 281 ---
 282 ### blocks/list (*; AUTH)
 283
 284 #### Parameters
 285
 286 * include_entities: "true" shows entities for pictures and links (Default: false)
 287 * count: Items per page (default: 20).
 288 * page: page number
 289
 290 #### Unsupported parameters
 291 * cursor
 292 * skip_status
 293
 294 ---
 295 ### statuses/friends_timeline (*; AUTH)
 296 #### Parameters
 297 * count: Items per page (default: 20)
 298 * page: page number
 299 * since_id: minimum id
 300 * max_id: maximum id
 301 * exclude_replies: don't show replies (default: false)
 302 * conversation_id: Shows all statuses of a given conversation.
 303 * include_entities: "true" shows entities for pictures and links (Default: false)
 304
 305 #### Unsupported parameters
 306 * include_rts
 307 * trim_user
 308 * contributor_details
 309
 310 ---
 311 ### statuses/home_timeline (*; AUTH)
 312 #### Parameters
 313 * count: Items per page (default: 20)
 314 * page: page number
 315 * since_id: minimum id
 316 * max_id: maximum id
 317 * exclude_replies: don't show replies (default: false)
 318 * conversation_id: Shows all statuses of a given conversation.
 319 * include_entities: "true" shows entities for pictures and links (Default: false)
 320
 321 #### Unsupported parameters
 322 * include_rts
 323 * trim_user
 324 * contributor_details
 325
 326 ---
 327 ### statuses/mentions (*; AUTH)
 328 #### Parameters
 329 * count: Items per page (default: 20)
 330 * page: page number
 331 * since_id: minimum id
 332 * max_id: maximum id
 333 * include_entities: "true" shows entities for pictures and links (Default: false)
 334
 335 #### Unsupported parameters
 336 * include_rts
 337 * trim_user
 338 * contributor_details
 339
 340 ---
 341 ### statuses/public_timeline (*; AUTH)
 342 #### Parameters
 343 * count: Items per page (default: 20)
 344 * page: page number
 345 * since_id: minimum id
 346 * max_id: maximum id
 347 * exclude_replies: don't show replies (default: false)
 348 * conversation_id: Shows all statuses of a given conversation.
 349 * include_entities: "true" shows entities for pictures and links (Default: false)
 350
 351 #### Unsupported parameters
 352 * trim_user
 353
 354 ---
 355 ### statuses/networkpublic_timeline (*; AUTH)
 356 #### Parameters
 357 * count: Items per page (default: 20)
 358 * page: page number
 359 * since_id: minimum id
 360 * max_id: maximum id
 361 * include_entities: "true" shows entities for pictures and links (Default: false)
 362
 363 ---
 364 ### statuses/replies (*; AUTH)
 365 #### Parameters
 366 * count: Items per page (default: 20)
 367 * page: page number
 368 * since_id: minimum id
 369 * max_id: maximum id
 370 * include_entities: "true" shows entities for pictures and links (Default: false)
 371
 372 #### Unsupported parameters
 373 * include_rts
 374 * trim_user
 375 * contributor_details
 376
 377 ---
 378 ### statuses/retweet (POST,PUT; AUTH)
 379 #### Parameters
 380 * id: message number
 381 * include_entities: "true" shows entities for pictures and links (Default: false)
 382
 383 #### Unsupported parameters
 384 * trim_user
 385
 386 ---
 387 ### statuses/show (*; AUTH)
 388 #### Parameters
 389 * id: message number
 390 * conversation: if set to "1" show all messages of the conversation with the given id
 391 * include_entities: "true" shows entities for pictures and links (Default: false)
 392
 393 #### Unsupported parameters
 394 * include_my_retweet
 395 * trim_user
 396
 397 ---
 398 ### statuses/update, statuses/update_with_media
 399 #### Parameters
 400 * title: Title of the status
 401 * status: Status in text format
 402 * htmlstatus: Status in HTML format
 403 * in_reply_to_status_id
 404 * lat: latitude
 405 * long: longitude
 406 * media: image data
 407 * source: Application name
 408 * group_allow
 409 * contact_allow
 410 * group_deny
 411 * contact_deny
 412 * network
 413 * include_entities: "true" shows entities for pictures and links (Default: false)
 414 * media_ids: (By now only a single value, no array)
 415
 416 #### Unsupported parameters
 417 * trim_user
 418 * place_id
 419 * display_coordinates
 420
 421 ---
 422 ### statuses/user_timeline (*; AUTH)
 423 #### Parameters
 424 * user_id: id of the user
 425 * screen_name: screen name (for technical reasons, this value is not unique!)
 426 * count: Items per page (default: 20)
 427 * page: page number
 428 * since_id: minimum id
 429 * max_id: maximum id
 430 * exclude_replies: don't show replies (default: false)
 431 * conversation_id: Shows all statuses of a given conversation.
 432 * include_entities: "true" shows entities for pictures and links (Default: false)
 433
 434 #### Unsupported parameters
 435
 436 * include_rts
 437 * trim_user
 438 * contributor_details
 439
 440 ---
 441 ### statusnet/config (*)
 442
 443 ---
 444 ### statusnet/conversation (*; AUTH)
 445 It shows all direct answers (excluding the original post) to a given id.
 446
 447 #### Parameter
 448 * id: id of the post
 449 * count: Items per page (default: 20)
 450 * page: page number
 451 * since_id: minimum id
 452 * max_id: maximum id
 453 * include_entities: "true" shows entities for pictures and links (Default: false)
 454
 455 ---
 456 ### statusnet/version (*)
 457
 458 #### Unsupported parameters
 459 * user_id
 460 * screen_name
 461 * cursor
 462
 463 Friendica doesn't allow showing followers of other users.
 464
 465 ---
 466 ### search (*; AUTH)
 467 #### Parameters
 468 * q: search query
 469 * page: the page number (starting at 1) to return
 470 * rpp: the number of statuses to return per page
 471 * count: alias for the rpp parameter
 472 * since_id: returns statuses with ids greater than the given id
 473 * max_id: returns statuses with ids lower or equal to the given id
 474
 475 #### Unsupported parameters
 476 * geocode
 477 * lang
 478 * locale
 479 * result_type
 480 * until
 481 * include_entities
 482
 483 ---
 484 ### users/search (*)
 485 #### Parameters
 486 * q: name of the user
 487
 488 #### Unsupported parameters
 489 * page
 490 * count
 491 * include_entities
 492
 493 ---
 494 ### users/show (*)
 495 #### Parameters
 496 * user_id: id of the user
 497 * screen_name: screen name (for technical reasons, this value is not unique!)
 498 * include_entities: "true" shows entities for pictures and links (Default: false)
 499
 500 #### Unsupported parameters
 501 * user_id
 502 * screen_name
 503 * cursor
 504
 505 Friendica doesn't allow showing friends of other users.
 506
 507
 508 ---
 509 ### account/update_profile_image (POST; AUTH)
 510 #### Parameters
 511 * image: image data as base64 (Twitter has a limit of 700kb, Friendica allows more)
 512 * profile_id (optional): id of the profile for which the image should be used, default is changing the default profile
 513
 514 uploads a new profile image (scales 4-6) to database, changes default or specified profile to the new photo
 515
 516 #### Return values
 517
 518 On success:
 519 * JSON return: returns the updated user details (see account/verify_credentials)
 520
 521 On error:
 522 * 403 FORBIDDEN: if not authenticated
 523 * 400 BADREQUEST: "no media data submitted", "profile_id not available"
 524 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
 525                         "image size exceeds Friendica Config setting (uploaded size: x)",
 526                         "unable to process image data",
 527                         "image upload failed"
 528
 529
 530 ## Implemented API calls (not compatible with other APIs)
 531
 532
 533 ---
 534 ### friendica/activity/<verb>
 535 #### parameters
 536 * id: item id
 537
 538 Add or remove an activity from an item.
 539 'verb' can be one of:
 540
 541 - like
 542 - dislike
 543 - attendyes
 544 - attendno
 545 - attendmaybe
 546
 547 To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"
 548 Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".
 549 Attend verbs should be used only with event-related items (there is no check at the moment)
 550
 551 #### Return values
 552
 553 On success:
 554 json
 555 ```"ok"```
 556
 557 xml
 558 ```<ok>true</ok>```
 559
 560 On error:
 561 HTTP 400 BadRequest
 562
 563 ---
 564 ### friendica/group_show (*; AUTH)
 565 Return all or a specified group of the user with the containing contacts as array.
 566
 567 #### Parameters
 568 * gid: optional, if not given, API returns all groups of the user
 569
 570 #### Return values
 571 Array of:
 572
 573 * name: name of the group
 574 * gid: id of the group
 575 * user: array of group members (return from api_get_user() function for each member)
 576
 577
 578 ---
 579 ### friendica/group_delete (POST,DELETE; AUTH)
 580 delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted.
 581
 582 #### Parameters
 583 * gid: id of the group to be deleted
 584 * name: name of the group to be deleted
 585
 586 #### Return values
 587 Array of:
 588
 589 * success: true if successfully deleted
 590 * gid: gid of the deleted group
 591 * name: name of the deleted group
 592 * status: „deleted“ if successfully deleted
 593 * wrong users: empty array
 594
 595
 596 ---
 597 ### friendica/group_create (POST,PUT; AUTH)
 598 Create the group with the posted array of contacts as members.
 599
 600 #### Parameters
 601 * name: name of the group to be created
 602
 603 #### POST data
 604 JSON data as Array like the result of "users/group_show":
 605
 606 * gid
 607 * name
 608 * array of users
 609
 610 #### Return values
 611 Array of:
 612
 613 * success: true if successfully created or reactivated
 614 * gid: gid of the created group
 615 * name: name of the created group
 616 * status: „missing user“ | „reactivated“ | „ok“
 617 * wrong users: array of users, which were not available in the contact table
 618
 619
 620 ---
 621 ### friendica/group_update (POST)
 622 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).
 623
 624 #### Parameters
 625 * gid: id of the group to be changed
 626 * name: name of the group to be changed
 627
 628 #### POST data
 629 JSON data as array like the result of „users/group_show“:
 630
 631 * gid
 632 * name
 633 * array of users
 634
 635 #### Return values
 636 Array of:
 637
 638 * success: true if successfully updated
 639 * gid: gid of the changed group
 640 * name: name of the changed group
 641 * status: „missing user“ | „ok“
 642 * wrong users: array of users, which were not available in the contact table
 643
 644
 645
 646 ---
 647 ### friendica/notifications (GET)
 648 Return last 50 notification for current user, ordered by date with unseen item on top
 649
 650 #### Parameters
 651 none
 652
 653 #### Return values
 654 Array of:
 655
 656 * id: id of the note
 657 * type: type of notification as int (see NOTIFY_* constants in boot.php)
 658 * name: full name of the contact subject of the note
 659 * url: contact's profile url
 660 * photo: contact's profile photo
 661 * date: datetime string of the note
 662 * timestamp: timestamp of the node
 663 * date_rel: relative date of the note (eg. "1 hour ago")
 664 * msg: note message in bbcode
 665 * msg_html: note message in html
 666 * msg_plain: note message in plain text
 667 * link: link to note
 668 * seen: seen state: 0 or 1
 669
 670
 671 ---
 672 ### friendica/notifications/seen (POST)
 673 Set note as seen, returns item object if possible
 674
 675 #### Parameters
 676 id: id of the note to set seen
 677
 678 #### Return values
 679 If the note is linked to an item, the item is returned, just like one of the "statuses/*_timeline" api.
 680
 681 If the note is not linked to an item, a success status is returned:
 682
 683 * "success" (json) | <status>success</status>;" (xml)
 684
 685
 686 ---
 687 ### friendica/photo (*; AUTH)
 688 #### Parameters
 689 * photo_id: Resource id of a photo.
 690 * scale: (optional) scale value of the photo
 691
 692 Returns data of a picture with the given resource.
 693 If 'scale' isn't provided, returned data include full url to each scale of the photo.
 694 If 'scale' is set, returned data include image data base64 encoded.
 695
 696 possibile scale value are:
 697
 698 * 0: original or max size by server settings
 699 * 1: image with or height at <= 640
 700 * 2: image with or height at <= 320
 701 * 3: thumbnail 160x160
 702 * 4: Profile image at 175x175
 703 * 5: Profile image at 80x80
 704 * 6: Profile image at 48x48
 705
 706 An image used as profile image has only scale 4-6, other images only 0-3
 707
 708 #### Return values
 709
 710 json
 711 ```
 712         {
 713                 "id": "photo id"
 714                 "created": "date(YYYY-MM-DD HH:MM:SS)",
 715                 "edited": "date(YYYY-MM-DD HH:MM:SS)",
 716                 "title": "photo title",
 717                 "desc": "photo description",
 718                 "album": "album name",
 719                 "filename": "original file name",
 720                 "type": "mime type",
 721                 "height": "number",
 722                 "width": "number",
 723                 "profile": "1 if is profile photo",
 724                 "link": {
 725                         "<scale>": "url to image"
 726                         ...
 727                 },
 728                 // if 'scale' is set
 729                 "datasize": "size in byte",
 730                 "data": "base64 encoded image data"
 731         }
 732 ```
 733
 734 xml
 735 ```
 736         <photo>
 737                 <id>photo id</id>
 738                 <created>date(YYYY-MM-DD HH:MM:SS)</created>
 739                 <edited>date(YYYY-MM-DD HH:MM:SS)</edited>
 740                 <title>photo title</title>
 741                 <desc>photo description</desc>
 742                 <album>album name</album>
 743                 <filename>original file name</filename>
 744                 <type>mime type</type>
 745                 <height>number</height>
 746                 <width>number</width>
 747                 <profile>1 if is profile photo</profile>
 748                 <links type="array">
 749                 <link type="mime type" scale="scale number" href="image url"/>
 750                         ...
 751                 </links>
 752         </photo>
 753 ```
 754
 755 ---
 756 ### friendica/photos/list (*; AUTH)
 757
 758 Returns a list of all photo resources of the logged in user.
 759
 760 #### Return values
 761
 762 json
 763 ```
 764         [
 765                 {
 766                         id: "resource_id",
 767                         album: "album name",
 768                         filename: "original file name",
 769                         type: "image mime type",
 770                         thumb: "url to thumb sized image"
 771                 },
 772                 ...
 773         ]
 774 ```
 775
 776 xml
 777 ```
 778         <photos type="array">
 779                 <photo id="resource_id"
 780                 album="album name"
 781                 filename="original file name"
 782                 type="image mime type">
 783                         "url to thumb sized image"
 784                 </photo>
 785                 ...
 786         </photos>
 787 ```
 788
 789 ---
 790 ### friendica/photoalbum/delete (POST,DELETE; AUTH)
 791 #### Parameters
 792 * album: name of the album to be deleted
 793
 794 deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this
 795
 796 #### Return values
 797
 798 On success:
 799 * JSON return {"result":"deleted","message":"album 'xyz' with all containing photos has been deleted."}
 800
 801 On error:
 802 * 403 FORBIDDEN: if not authenticated
 803 * 400 BADREQUEST: "no albumname specified", "album not available"
 804 * 500 INTERNALSERVERERROR: "problem with deleting item occured", "unknown error - deleting from database failed"
 805
 806
 807 ---
 808 ### friendica/photoalbum/update (POST,PUT; AUTH)
 809 #### Parameters
 810 * album: name of the album to be updated
 811 * album_new: new name of the album
 812
 813 changes the album name to album_new for all photos in album
 814
 815 #### Return values
 816
 817 On success:
 818 * JSON return {"result":"updated","message":"album 'abc' with all containing photos has been renamed to 'xyz'."}
 819
 820 On error:
 821 * 403 FORBIDDEN: if not authenticated
 822 * 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available"
 823 * 500 INTERNALSERVERERROR: "unknown error - updating in database failed"
 824
 825
 826 ---
 827 ### friendica/photo/create (POST; AUTH)
 828 ### friendica/photo/update (POST; AUTH)
 829 #### Parameters
 830 * photo_id (optional): if specified the photo with this id will be updated
 831 * media (optional): image data as base64, only optional if photo_id is specified (new upload must have media)
 832 * desc (optional): description for the photo, updated when photo_id is specified
 833 * album: name of the album to be deleted (always necessary)
 834 * album_new (optional): can be used to change the album of a single photo if photo_id is specified
 835 * 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;
 836                         on update: keys need to be present with empty values for changing a private photo to public
 837
 838 both calls point to one function for creating AND updating photos.
 839 Saves data for the scales 0-2 to database (see above for scale description).
 840 Call adds non-visible entries to items table to enable authenticated contacts to comment/like the photo.
 841 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.
 842 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.
 843
 844 #### Return values
 845
 846 On success:
 847 * new photo uploaded: JSON return with photo data (see friendica/photo)
 848 * photo updated - changed photo data: JSON return with photo data (see friendica/photo)
 849 * photo updated - changed info: JSON return {"result":"updated","message":"Image id 'xyz' has been updated."}
 850 * photo updated - nothing changed: JSON return {"result":"cancelled","message":"Nothing to update for image id 'xyz'."}
 851
 852 On error:
 853 * 403 FORBIDDEN: if not authenticated
 854 * 400 BADREQUEST: "no albumname specified", "no media data submitted", "photo not available", "acl data invalid"
 855 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
 856                         "image size exceeds Friendica Config setting (uploaded size: x)",
 857                         "unable to process image data",
 858                         "image upload failed",
 859                         "unknown error - uploading photo failed, see Friendica log for more information",
 860                         "unknown error - update photo entry in database failed",
 861                         "unknown error - this error on uploading or updating a photo should never happen"
 862
 863
 864 ---
 865 ### friendica/photo/delete (DELETE; AUTH)
 866 #### Parameters
 867 * photo_id: id of the photo to be deleted
 868
 869 deletes a single image with the specified id, is not reversible -> ensure that client is asking user for being sure to do this
 870 Sets item table entries for this photo to deleted = 1
 871
 872 #### Return values
 873
 874 On success:
 875 * JSON return {"result":"deleted","message":"photo with id 'xyz' has been deleted from server."}
 876
 877 On error:
 878 * 403 FORBIDDEN: if not authenticated
 879 * 400 BADREQUEST: "no photo_id specified", "photo not available"
 880 * 500 INTERNALSERVERERROR: "unknown error on deleting photo", "problem with deleting items occurred"
 881
 882
 883 ---
 884 ### friendica/direct_messages_setseen (GET; AUTH)
 885 #### Parameters
 886 * id: id of the message to be updated as seen
 887
 888 #### Return values
 889
 890 On success:
 891 * JSON return {"result":"ok","message":"message set to seen"}
 892
 893 On error:
 894 * different JSON returns {"result":"error","message":"xyz"}
 895
 896 ---
 897 ### friendica/direct_messages_search (GET; AUTH)
 898 #### Parameters
 899 * searchstring: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored)
 900
 901 #### Return values
 902 Returns only tested with JSON, XML might work as well.
 903
 904 On success:
 905 * JSON return {"success":"true","search_results": array of found messages}
 906 * JSOn return {"success":"false","search_results":"nothing found"}
 907
 908 On error:
 909 * different JSON returns {"result":"error","message":"searchstring not specified"}
 910
 911 ---
 912 ### friendica/profile/show (GET; AUTH)
 913 show data of all profiles or a single profile of the authenticated user
 914
 915 #### Parameters
 916 * profile_id: id of the profile to be returned (optional, if omitted all profiles are returned by default)
 917
 918 #### Return values
 919 On success: Array of:
 920
 921 * multi_profiles: true if user has activated multi_profiles
 922 * global_dir: URL of the global directory set in server settings
 923 * friendica_owner: user data of the authenticated user
 924 * profiles: array of the profile data
 925
 926 On error:
 927 HTTP 403 Forbidden: when no authentication was provided
 928 HTTP 400 Bad Request: if given profile_id is not in the database or is not assigned to the authenticated user
 929
 930 General description of profile data in API returns:
 931 * profile_id
 932 * profile_name
 933 * is_default: true if this is the public profile
 934 * hide_friends: true if friends are hidden
 935 * profile_photo
 936 * profile_thumb
 937 * publish: true if published on the server's local directory
 938 * net_publish: true if published to global_dir
 939 * description ... homepage: different data fields from 'profile' table in database
 940 * users: array with the users allowed to view this profile (empty if is_default=true)
 941
 942
 943 ---
 944 ## Not Implemented API calls
 945 The following API calls are implemented in GNU Social but not in Friendica: (incomplete)
 946
 947 * statuses/retweets_of_me
 948 * friendships/create
 949 * friendships/destroy
 950 * friendships/exists
 951 * friendships/show
 952 * account/update_profile_background_image
 953 * blocks/create
 954 * blocks/destroy
 955
 956 The following API calls from the Twitter API are not implemented in either Friendica or GNU Social:
 957
 958 * statuses/mentions_timeline
 959 * statuses/retweets/:id
 960 * statuses/oembed
 961 * statuses/retweeters/ids
 962 * statuses/lookup
 963 * direct_messages/show
 964 * search/tweets
 965 * friendships/no_retweets/ids
 966 * friendships/incoming
 967 * friendships/outgoing
 968 * friendships/update
 969 * friends/list
 970 * friendships/lookup
 971 * account/settings
 972 * account/update_delivery_device
 973 * account/update_profile
 974 * account/update_profile_background_image
 975 * blocks/ids
 976 * users/lookup
 977 * users/show
 978 * users/search
 979 * account/remove_profile_banner
 980 * account/update_profile_banner
 981 * users/profile_banner
 982 * mutes/users/create
 983 * mutes/users/destroy
 984 * mutes/users/ids
 985 * mutes/users/list
 986 * users/suggestions/:slug
 987 * users/suggestions
 988 * users/suggestions/:slug/members
 989 * favorites/list
 990 * lists/list
 991 * lists/statuses
 992 * lists/members/destroy
 993 * lists/memberships
 994 * lists/subscribers
 995 * lists/subscribers/create
 996 * lists/subscribers/show
 997 * lists/subscribers/destroy
 998 * lists/members/create_all
 999 * lists/members/show
1000 * lists/members
1001 * lists/members/create
1002 * lists/destroy
1003 * lists/update
1004 * lists/create
1005 * lists/show
1006 * lists/subscriptions
1007 * lists/members/destroy_all
1008 * lists/ownerships
1009 * saved_searches/list
1010 * saved_searches/show/:id
1011 * saved_searches/create
1012 * saved_searches/destroy/:id
1013 * geo/id/:place_id
1014 * geo/reverse_geocode
1015 * geo/search
1016 * geo/place
1017 * trends/place
1018 * trends/available
1019 * help/configuration
1020 * help/languages
1021 * help/privacy
1022 * help/tos
1023 * trends/closest
1024 * users/report_spam
1025
1026 ---
1027
1028 ---
1029
1030 ## Usage Examples
1031 ### BASH / cURL
1032
1033 /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"
1034
1035 ### Python
1036 The [RSStoFriedika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python.
1037 The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.
1038
1039 def tweet(server, message, group_allow=None):
1040 url = server + '/api/statuses/update'
1041 urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))
1042
1043 There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.