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 ### users/lookup (*; AUTH)
 509
 510 #### Parameters
 511 * user_id: list of ids to lookup
 512
 513 #### Unsupported parameters
 514 * screen_name
 515 * include_entities
 516
 517 ---
 518 ### account/update_profile_image (POST; AUTH)
 519 #### Parameters
 520 * image: image data as base64 (Twitter has a limit of 700kb, Friendica allows more)
 521 * profile_id (optional): id of the profile for which the image should be used, default is changing the default profile
 522
 523 uploads a new profile image (scales 4-6) to database, changes default or specified profile to the new photo
 524
 525 #### Return values
 526
 527 On success:
 528 * JSON return: returns the updated user details (see account/verify_credentials)
 529
 530 On error:
 531 * 403 FORBIDDEN: if not authenticated
 532 * 400 BADREQUEST: "no media data submitted", "profile_id not available"
 533 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
 534                         "image size exceeds Friendica Config setting (uploaded size: x)",
 535                         "unable to process image data",
 536                         "image upload failed"
 537
 538
 539 ## Implemented API calls (not compatible with other APIs)
 540
 541
 542 ---
 543 ### friendica/activity/<verb>
 544 #### parameters
 545 * id: item id
 546
 547 Add or remove an activity from an item.
 548 'verb' can be one of:
 549
 550 - like
 551 - dislike
 552 - attendyes
 553 - attendno
 554 - attendmaybe
 555
 556 To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"
 557 Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".
 558 Attend verbs should be used only with event-related items (there is no check at the moment)
 559
 560 #### Return values
 561
 562 On success:
 563 json
 564 ```"ok"```
 565
 566 xml
 567 ```<ok>true</ok>```
 568
 569 On error:
 570 HTTP 400 BadRequest
 571
 572 ---
 573 ### friendica/group_show (*; AUTH)
 574 Return all or a specified group of the user with the containing contacts as array.
 575
 576 #### Parameters
 577 * gid: optional, if not given, API returns all groups of the user
 578
 579 #### Return values
 580 Array of:
 581
 582 * name: name of the group
 583 * gid: id of the group
 584 * user: array of group members (return from api_get_user() function for each member)
 585
 586
 587 ---
 588 ### friendica/group_delete (POST,DELETE; AUTH)
 589 delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted.
 590
 591 #### Parameters
 592 * gid: id of the group to be deleted
 593 * name: name of the group to be deleted
 594
 595 #### Return values
 596 Array of:
 597
 598 * success: true if successfully deleted
 599 * gid: gid of the deleted group
 600 * name: name of the deleted group
 601 * status: „deleted“ if successfully deleted
 602 * wrong users: empty array
 603
 604
 605 ---
 606 ### friendica/group_create (POST,PUT; AUTH)
 607 Create the group with the posted array of contacts as members.
 608
 609 #### Parameters
 610 * name: name of the group to be created
 611
 612 #### POST data
 613 JSON data as Array like the result of "users/group_show":
 614
 615 * gid
 616 * name
 617 * array of users
 618
 619 #### Return values
 620 Array of:
 621
 622 * success: true if successfully created or reactivated
 623 * gid: gid of the created group
 624 * name: name of the created group
 625 * status: „missing user“ | „reactivated“ | „ok“
 626 * wrong users: array of users, which were not available in the contact table
 627
 628
 629 ---
 630 ### friendica/group_update (POST)
 631 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).
 632
 633 #### Parameters
 634 * gid: id of the group to be changed
 635 * name: name of the group to be changed
 636
 637 #### POST data
 638 JSON data as array like the result of „users/group_show“:
 639
 640 * gid
 641 * name
 642 * array of users
 643
 644 #### Return values
 645 Array of:
 646
 647 * success: true if successfully updated
 648 * gid: gid of the changed group
 649 * name: name of the changed group
 650 * status: „missing user“ | „ok“
 651 * wrong users: array of users, which were not available in the contact table
 652
 653
 654
 655 ---
 656 ### friendica/notifications (GET)
 657 Return last 50 notification for current user, ordered by date with unseen item on top
 658
 659 #### Parameters
 660 none
 661
 662 #### Return values
 663 Array of:
 664
 665 * id: id of the note
 666 * type: type of notification as int (see NOTIFY_* constants in boot.php)
 667 * name: full name of the contact subject of the note
 668 * url: contact's profile url
 669 * photo: contact's profile photo
 670 * date: datetime string of the note
 671 * timestamp: timestamp of the node
 672 * date_rel: relative date of the note (eg. "1 hour ago")
 673 * msg: note message in bbcode
 674 * msg_html: note message in html
 675 * msg_plain: note message in plain text
 676 * link: link to note
 677 * seen: seen state: 0 or 1
 678
 679
 680 ---
 681 ### friendica/notifications/seen (POST)
 682 Set note as seen, returns item object if possible
 683
 684 #### Parameters
 685 id: id of the note to set seen
 686
 687 #### Return values
 688 If the note is linked to an item, the item is returned, just like one of the "statuses/*_timeline" api.
 689
 690 If the note is not linked to an item, a success status is returned:
 691
 692 * "success" (json) | <status>success</status>;" (xml)
 693
 694
 695 ---
 696 ### friendica/photo (*; AUTH)
 697 #### Parameters
 698 * photo_id: Resource id of a photo.
 699 * scale: (optional) scale value of the photo
 700
 701 Returns data of a picture with the given resource.
 702 If 'scale' isn't provided, returned data include full url to each scale of the photo.
 703 If 'scale' is set, returned data include image data base64 encoded.
 704
 705 possibile scale value are:
 706
 707 * 0: original or max size by server settings
 708 * 1: image with or height at <= 640
 709 * 2: image with or height at <= 320
 710 * 3: thumbnail 160x160
 711 * 4: Profile image at 175x175
 712 * 5: Profile image at 80x80
 713 * 6: Profile image at 48x48
 714
 715 An image used as profile image has only scale 4-6, other images only 0-3
 716
 717 #### Return values
 718
 719 json
 720 ```
 721         {
 722                 "id": "photo id"
 723                 "created": "date(YYYY-MM-DD HH:MM:SS)",
 724                 "edited": "date(YYYY-MM-DD HH:MM:SS)",
 725                 "title": "photo title",
 726                 "desc": "photo description",
 727                 "album": "album name",
 728                 "filename": "original file name",
 729                 "type": "mime type",
 730                 "height": "number",
 731                 "width": "number",
 732                 "profile": "1 if is profile photo",
 733                 "link": {
 734                         "<scale>": "url to image"
 735                         ...
 736                 },
 737                 // if 'scale' is set
 738                 "datasize": "size in byte",
 739                 "data": "base64 encoded image data"
 740         }
 741 ```
 742
 743 xml
 744 ```
 745         <photo>
 746                 <id>photo id</id>
 747                 <created>date(YYYY-MM-DD HH:MM:SS)</created>
 748                 <edited>date(YYYY-MM-DD HH:MM:SS)</edited>
 749                 <title>photo title</title>
 750                 <desc>photo description</desc>
 751                 <album>album name</album>
 752                 <filename>original file name</filename>
 753                 <type>mime type</type>
 754                 <height>number</height>
 755                 <width>number</width>
 756                 <profile>1 if is profile photo</profile>
 757                 <links type="array">
 758                 <link type="mime type" scale="scale number" href="image url"/>
 759                         ...
 760                 </links>
 761         </photo>
 762 ```
 763
 764 ---
 765 ### friendica/photos/list (*; AUTH)
 766
 767 Returns a list of all photo resources of the logged in user.
 768
 769 #### Return values
 770
 771 json
 772 ```
 773         [
 774                 {
 775                         id: "resource_id",
 776                         album: "album name",
 777                         filename: "original file name",
 778                         type: "image mime type",
 779                         thumb: "url to thumb sized image"
 780                 },
 781                 ...
 782         ]
 783 ```
 784
 785 xml
 786 ```
 787         <photos type="array">
 788                 <photo id="resource_id"
 789                 album="album name"
 790                 filename="original file name"
 791                 type="image mime type">
 792                         "url to thumb sized image"
 793                 </photo>
 794                 ...
 795         </photos>
 796 ```
 797
 798 ---
 799 ### friendica/photoalbum/delete (POST,DELETE; AUTH)
 800 #### Parameters
 801 * album: name of the album to be deleted
 802
 803 deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this
 804
 805 #### Return values
 806
 807 On success:
 808 * JSON return {"result":"deleted","message":"album 'xyz' with all containing photos has been deleted."}
 809
 810 On error:
 811 * 403 FORBIDDEN: if not authenticated
 812 * 400 BADREQUEST: "no albumname specified", "album not available"
 813 * 500 INTERNALSERVERERROR: "problem with deleting item occured", "unknown error - deleting from database failed"
 814
 815
 816 ---
 817 ### friendica/photoalbum/update (POST,PUT; AUTH)
 818 #### Parameters
 819 * album: name of the album to be updated
 820 * album_new: new name of the album
 821
 822 changes the album name to album_new for all photos in album
 823
 824 #### Return values
 825
 826 On success:
 827 * JSON return {"result":"updated","message":"album 'abc' with all containing photos has been renamed to 'xyz'."}
 828
 829 On error:
 830 * 403 FORBIDDEN: if not authenticated
 831 * 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available"
 832 * 500 INTERNALSERVERERROR: "unknown error - updating in database failed"
 833
 834
 835 ---
 836 ### friendica/photo/create (POST; AUTH)
 837 ### friendica/photo/update (POST; AUTH)
 838 #### Parameters
 839 * photo_id (optional): if specified the photo with this id will be updated
 840 * media (optional): image data as base64, only optional if photo_id is specified (new upload must have media)
 841 * desc (optional): description for the photo, updated when photo_id is specified
 842 * album: name of the album to be deleted (always necessary)
 843 * album_new (optional): can be used to change the album of a single photo if photo_id is specified
 844 * 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;
 845                         on update: keys need to be present with empty values for changing a private photo to public
 846
 847 both calls point to one function for creating AND updating photos.
 848 Saves data for the scales 0-2 to database (see above for scale description).
 849 Call adds non-visible entries to items table to enable authenticated contacts to comment/like the photo.
 850 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.
 851 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.
 852
 853 #### Return values
 854
 855 On success:
 856 * new photo uploaded: JSON return with photo data (see friendica/photo)
 857 * photo updated - changed photo data: JSON return with photo data (see friendica/photo)
 858 * photo updated - changed info: JSON return {"result":"updated","message":"Image id 'xyz' has been updated."}
 859 * photo updated - nothing changed: JSON return {"result":"cancelled","message":"Nothing to update for image id 'xyz'."}
 860
 861 On error:
 862 * 403 FORBIDDEN: if not authenticated
 863 * 400 BADREQUEST: "no albumname specified", "no media data submitted", "photo not available", "acl data invalid"
 864 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
 865                         "image size exceeds Friendica Config setting (uploaded size: x)",
 866                         "unable to process image data",
 867                         "image upload failed",
 868                         "unknown error - uploading photo failed, see Friendica log for more information",
 869                         "unknown error - update photo entry in database failed",
 870                         "unknown error - this error on uploading or updating a photo should never happen"
 871
 872
 873 ---
 874 ### friendica/photo/delete (DELETE; AUTH)
 875 #### Parameters
 876 * photo_id: id of the photo to be deleted
 877
 878 deletes a single image with the specified id, is not reversible -> ensure that client is asking user for being sure to do this
 879 Sets item table entries for this photo to deleted = 1
 880
 881 #### Return values
 882
 883 On success:
 884 * JSON return {"result":"deleted","message":"photo with id 'xyz' has been deleted from server."}
 885
 886 On error:
 887 * 403 FORBIDDEN: if not authenticated
 888 * 400 BADREQUEST: "no photo_id specified", "photo not available"
 889 * 500 INTERNALSERVERERROR: "unknown error on deleting photo", "problem with deleting items occurred"
 890
 891
 892 ---
 893 ### friendica/direct_messages_setseen (GET; AUTH)
 894 #### Parameters
 895 * id: id of the message to be updated as seen
 896
 897 #### Return values
 898
 899 On success:
 900 * JSON return {"result":"ok","message":"message set to seen"}
 901
 902 On error:
 903 * different JSON returns {"result":"error","message":"xyz"}
 904
 905 ---
 906 ### friendica/direct_messages_search (GET; AUTH)
 907 #### Parameters
 908 * searchstring: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored)
 909
 910 #### Return values
 911 Returns only tested with JSON, XML might work as well.
 912
 913 On success:
 914 * JSON return {"success":"true","search_results": array of found messages}
 915 * JSOn return {"success":"false","search_results":"nothing found"}
 916
 917 On error:
 918 * different JSON returns {"result":"error","message":"searchstring not specified"}
 919
 920 ---
 921 ### friendica/profile/show (GET; AUTH)
 922 show data of all profiles or a single profile of the authenticated user
 923
 924 #### Parameters
 925 * profile_id: id of the profile to be returned (optional, if omitted all profiles are returned by default)
 926
 927 #### Return values
 928 On success: Array of:
 929
 930 * multi_profiles: true if user has activated multi_profiles
 931 * global_dir: URL of the global directory set in server settings
 932 * friendica_owner: user data of the authenticated user
 933 * profiles: array of the profile data
 934
 935 On error:
 936 HTTP 403 Forbidden: when no authentication was provided
 937 HTTP 400 Bad Request: if given profile_id is not in the database or is not assigned to the authenticated user
 938
 939 General description of profile data in API returns:
 940 * profile_id
 941 * profile_name
 942 * is_default: true if this is the public profile
 943 * hide_friends: true if friends are hidden
 944 * profile_photo
 945 * profile_thumb
 946 * publish: true if published on the server's local directory
 947 * net_publish: true if published to global_dir
 948 * description ... homepage: different data fields from 'profile' table in database
 949 * users: array with the users allowed to view this profile (empty if is_default=true)
 950
 951 ---
 952 ### friendships/incoming (*; AUTH)
 953
 954 #### Unsupported parameters
 955 * cursor
 956 * stringify_ids
 957
 958 ---
 959 ## Not Implemented API calls
 960 The following API calls are implemented in GNU Social but not in Friendica: (incomplete)
 961
 962 * statuses/retweets_of_me
 963 * friendships/create
 964 * friendships/destroy
 965 * friendships/exists
 966 * friendships/show
 967 * account/update_profile_background_image
 968 * blocks/create
 969 * blocks/destroy
 970
 971 The following API calls from the Twitter API are not implemented in either Friendica or GNU Social:
 972
 973 * statuses/mentions_timeline
 974 * statuses/retweets/:id
 975 * statuses/oembed
 976 * statuses/retweeters/ids
 977 * statuses/lookup
 978 * direct_messages/show
 979 * search/tweets
 980 * friendships/no_retweets/ids
 981 * friendships/outgoing
 982 * friendships/update
 983 * friends/list
 984 * friendships/lookup
 985 * account/settings
 986 * account/update_delivery_device
 987 * account/update_profile
 988 * account/update_profile_background_image
 989 * blocks/ids
 990 * users/show
 991 * users/search
 992 * account/remove_profile_banner
 993 * account/update_profile_banner
 994 * users/profile_banner
 995 * mutes/users/create
 996 * mutes/users/destroy
 997 * mutes/users/ids
 998 * mutes/users/list
 999 * users/suggestions/:slug
1000 * users/suggestions
1001 * users/suggestions/:slug/members
1002 * favorites/list
1003 * lists/list
1004 * lists/statuses
1005 * lists/members/destroy
1006 * lists/memberships
1007 * lists/subscribers
1008 * lists/subscribers/create
1009 * lists/subscribers/show
1010 * lists/subscribers/destroy
1011 * lists/members/create_all
1012 * lists/members/show
1013 * lists/members
1014 * lists/members/create
1015 * lists/destroy
1016 * lists/update
1017 * lists/create
1018 * lists/show
1019 * lists/subscriptions
1020 * lists/members/destroy_all
1021 * lists/ownerships
1022 * saved_searches/list
1023 * saved_searches/show/:id
1024 * saved_searches/create
1025 * saved_searches/destroy/:id
1026 * geo/id/:place_id
1027 * geo/reverse_geocode
1028 * geo/search
1029 * geo/place
1030 * trends/place
1031 * trends/available
1032 * help/configuration
1033 * help/languages
1034 * help/privacy
1035 * help/tos
1036 * trends/closest
1037 * users/report_spam
1038
1039 ---
1040
1041 ---
1042
1043 ## Usage Examples
1044 ### BASH / cURL
1045
1046 /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"
1047
1048 ### Python
1049 The [RSStoFriedika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python.
1050 The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.
1051
1052 def tweet(server, message, group_allow=None):
1053 url = server + '/api/statuses/update'
1054 urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))
1055
1056 There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.