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