doc/API-Friendica.md

   1 # Friendica API
   2
   3 * [Home](help)
   4   * [Using the APIs](help/api)
   5
   6 ## Overview
   7
   8 Friendica provides the following specific endpoints.
   9
  10 Authentication is the same as described in [Using the APIs](help/api#Authentication).
  11
  12 ## Entities
  13
  14 These endpoints uses the [Friendica API entities](help/API-Entities).
  15
  16 ## Endpoints
  17
  18 ### GET api/friendica/events
  19
  20 Returns a list of [Event](help/API-Entities#Event) entities for the current logged in user.
  21
  22 #### Parameters
  23
  24 - `since_id`: (optional) minimum event id for pagination
  25 - `count`: maximum number of items returned, default 20
  26
  27 ### GET api/externalprofile/show
  28
  29 Returns a [Contact](help/API-Entities#Contact) entity for the provided profile URL.
  30
  31 #### Parameters
  32
  33 - `profileurl`: Profile URL
  34
  35 ### GET api/statuses/public_timeline
  36
  37 Returns a list of public [Items](help/API-Entities#Item) posted on this node.
  38 Equivalent of the local community page.
  39
  40 #### Parameters
  41
  42 * `count`: Items per page (default: 20)
  43 * `page`: page number
  44 * `since_id`: minimum id
  45 * `max_id`: maximum id
  46 * `exclude_replies`: don't show replies (default: false)
  47 * `conversation_id`: Shows all statuses of a given conversation.
  48 * `include_entities`: "true" shows entities for pictures and links (Default: false)
  49
  50 #### Unsupported parameters
  51
  52 * `trim_user`
  53
  54 ### GET api/statuses/networkpublic_timeline
  55
  56 Returns a list of public [Items](help/API-Entities#Item) this node is aware of.
  57 Equivalent of the global community page.
  58
  59 #### Parameters
  60
  61 * `count`: Items per page (default: 20)
  62 * `page`: page number
  63 * `since_id`: minimum id
  64 * `max_id`: maximum id
  65 * `exclude_replies`: don't show replies (default: false)
  66 * `conversation_id`: Shows all statuses of a given conversation.
  67 * `include_entities`: "true" shows entities for pictures and links (Default: false)
  68
  69 ### GET api/statuses/replies
  70
  71 #### Parameters
  72
  73 * `count`: Items per page (default: 20)
  74 * `page`: page number
  75 * `since_id`: minimum id
  76 * `max_id`: maximum id
  77 * `include_entities`: "true" shows entities for pictures and links (Default: false)
  78
  79 #### Unsupported parameters
  80
  81 * `include_rts`
  82 * `trim_user`
  83 * `contributor_details`
  84
  85 ---
  86
  87 ### GET api/conversation/show
  88
  89 Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
  90
  91 #### Parameters
  92
  93 * `id`: id of the post
  94 * `count`: Items per page (default: 20)
  95 * `page`: page number
  96 * `since_id`: minimum id
  97 * `max_id`: maximum id
  98 * `include_entities`: "true" shows entities for pictures and links (Default: false)
  99
 100 #### Unsupported parameters
 101
 102 * `include_rts`
 103 * `trim_user`
 104 * `contributor_details`
 105
 106 ### GET api/statusnet/conversation
 107
 108 Alias of [`api/conversation/show`](#GET+api%2Fconversation%2Fshow).
 109
 110 ### GET api/statusnet/config
 111
 112 Returns the public Friendica node configuration.
 113
 114 ### GET api/gnusocial/config
 115
 116 Alias of [`api/statusnet/config`](#GET+api%2Fstatusnet%2Fconfig).
 117
 118 ### GET api/statusnet/version
 119
 120 Returns a fake static StatusNet protocol version.
 121
 122 ### GET api/gnusocial/version
 123
 124 Alias of [`api/statusnet/version`](#GET+api%2Fstatusnet%2Fversion).
 125
 126 ---
 127
 128 ### POST api/friendica/activity/[verb]
 129
 130 Add or remove an activity from an item.
 131 'verb' can be one of:
 132
 133 * `like`
 134 * `dislike`
 135 * `attendyes`
 136 * `attendno`
 137 * `attendmaybe`
 138
 139 To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"
 140 Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".
 141 Attend verbs should be used only with event-related items (there is no check at the moment).
 142
 143 #### Parameters
 144
 145 * `id`: item id
 146
 147 #### Return values
 148
 149 On success:
 150 json:
 151
 152 ```"ok"```
 153
 154 xml:
 155
 156 ```<ok>true</ok>```
 157
 158 On error:
 159 HTTP 400 BadRequest
 160
 161 ---
 162
 163 ### GET api/direct_messages
 164
 165 Deprecated Twitter received direct message list endpoint.
 166
 167 #### Parameters
 168
 169 * `count`: Items per page (default: 20)
 170 * `page`: page number
 171 * `since_id`: minimum id
 172 * `max_id`: maximum id
 173 * `getText`: Defines the format of the status field. Can be "html" or "plain"
 174 * `include_entities`: "true" shows entities for pictures and links (Default: false)
 175 * `friendica_verbose`: "true" enables different error returns (default: "false")
 176
 177 #### Unsupported parameters
 178
 179 * `skip_status`
 180
 181 ### GET api/direct_messages/all
 182
 183 Returns all [Private Messages](help/API-Entities#Private+message).
 184
 185 #### Parameters
 186
 187 * `count`: Items per page (default: 20)
 188 * `page`: page number
 189 * `since_id`: minimum id
 190 * `max_id`: maximum id
 191 * `getText`: Defines the format of the status field. Can be "html" or "plain"
 192 * `friendica_verbose`: "true" enables different error returns (default: "false")
 193
 194 ### GET api/direct_messages/conversation
 195
 196 Returns all replies of a single private message conversation. Returns [Private Messages](help/API-Entities#Private+message)
 197
 198 #### Parameters
 199
 200 * `count`: Items per page (default: 20)
 201 * `page`: page number
 202 * `since_id`: minimum id
 203 * `max_id`: maximum id
 204 * `getText`: Defines the format of the status field. Can be "html" or "plain"
 205 * `uri`: URI of the conversation
 206 * `friendica_verbose`: "true" enables different error returns (default: "false")
 207
 208 ### GET api/direct_messages/sent
 209
 210 Deprecated Twitter sent direct message list endpoint. Returns [Private Messages](help/API-Entities#Private+message).
 211
 212 #### Parameters
 213
 214 * `count`: Items per page (default: 20)
 215 * `page`: page number
 216 * `since_id`: minimum id
 217 * `max_id`: maximum id
 218 * `getText`: Defines the format of the status field. Can be "html" or "plain"
 219 * `include_entities`: "true" shows entities for pictures and links (Default: false)
 220 * `friendica_verbose`: "true" enables different error returns (default: "false")
 221
 222
 223 ### POST/PUT api/direct_messages/new
 224
 225 Deprecated Twitter direct message submission endpoint.
 226
 227 #### Parameters
 228
 229 * `user_id`: id of the user
 230 * `screen_name`: screen name (for technical reasons, this value is not unique!)
 231 * `text`: The message
 232 * `replyto`: ID of the replied direct message
 233 * `title`: Title of the direct message
 234
 235 ### POST/DELETE api/direct_messages/destroy
 236
 237 Deprecated Twitter direct message deletion endpoint.
 238
 239 #### Parameters
 240
 241 * `id`: id of the message to be deleted
 242 * `include_entities`: optional, currently not yet implemented
 243 * `friendica_parenturi`: optional, can be used for increased safety to delete only intended messages
 244 * `friendica_verbose`: "true" enables different error returns (default: "false")
 245
 246 #### Return values
 247
 248 On success:
 249
 250 * JSON return as defined for Twitter API not yet implemented
 251 * on friendica_verbose=true: JSON return {"result":"ok","message":"message deleted"}
 252
 253 On error:
 254 HTTP 400 BadRequest
 255
 256 * on friendica_verbose=true: different JSON returns {"result":"error","message":"xyz"}
 257
 258 ### GET api/friendica/direct_messages_setseen
 259
 260 #### Parameters
 261
 262 * `id`: id of the message to be updated as seen
 263
 264 #### Return values
 265
 266 On success:
 267
 268 * JSON return `{"result": "ok", "message": "message set to seen"}`
 269
 270 On error:
 271
 272 * different JSON returns `{"result": "error", "message": "xyz"}`
 273
 274
 275 ### GET api/friendica/direct_messages_search (GET; AUTH)
 276
 277 Returns [Private Messages](help/API-Entities#Private+message) matching the provided search string.
 278
 279 #### Parameters
 280
 281 * `searchstring`: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored)
 282 * `getText` (optional): `plain`|`html` If ommited, the title is prepended to the plaintext body in the `text` attribute of the private message objects.
 283 * `getUserObjects` (optional): `true`|`false` If `false`, the `sender` and `recipient` attributes of the private message object are absent.
 284
 285 #### Return values
 286
 287 Returns only tested with JSON, XML might work as well.
 288
 289 On success:
 290
 291 * JSON return `{"success":"true", "search_results": array of found messages}`
 292 * JSOn return `{"success":"false", "search_results": "nothing found"}`
 293
 294 On error:
 295
 296 * different JSON returns `{"result": "error", "message": "searchstring not specified"}`
 297
 298 ---
 299
 300 ### GET api/friendica/group_show
 301
 302 Return all or a specified group of the user with the containing contacts as array.
 303
 304 #### Parameters
 305
 306 * `gid`: optional, if not given, API returns all groups of the user
 307
 308 #### Return values
 309
 310 Array of:
 311
 312 * `name`: name of the group
 313 * `gid`: id of the group
 314 * `user`: array of [Contacts](help/API-Entities#Contact)
 315
 316 ### POST/PUT api/friendica/group_create
 317
 318 Create the group with the posted array of contacts as members.
 319
 320 #### Parameters
 321
 322 * `name`: name of the group to be created
 323
 324 #### POST data
 325
 326 JSON data as Array like the result of [GET api/friendica/group_show](#GET+api%2Ffriendica%2Fgroup_show):
 327
 328 * `gid`
 329 * `name`
 330 * List of [Contacts](help/API-Entities#Contact)
 331
 332 #### Return values
 333
 334 Array of:
 335
 336 * `success`: true if successfully created or reactivated
 337 * `gid`: gid of the created group
 338 * `name`: name of the created group
 339 * `status`: "missing user" | "reactivated" | "ok"
 340 * `wrong users`: array of users, which were not available in the contact table
 341
 342 ### POST api/friendica/group_update
 343
 344 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).
 345
 346 #### Parameters
 347
 348 * `gid`: id of the group to be changed
 349 * `name`: name of the group to be changed
 350
 351 #### POST data
 352
 353 JSON data as array like the result of [GET api/friendica/group_show](#GET+api%2Ffriendica%2Fgroup_show):
 354
 355 * `gid`
 356 * `name`
 357 * List of [Contacts](help/API-Entities#Contact)
 358
 359 #### Return values
 360
 361 Array of:
 362
 363 * `success`: true if successfully updated
 364 * `gid`: gid of the changed group
 365 * `name`: name of the changed group
 366 * `status`: "missing user" | "ok"
 367 * `wrong users`: array of users, which were not available in the contact table
 368
 369 ### POST/DELETE api/friendica/group_delete
 370
 371 Delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted.
 372
 373 #### Parameters
 374
 375 * `gid`: id of the group to be deleted
 376 * `name`: name of the group to be deleted
 377
 378 #### Return values
 379
 380 Array of:
 381
 382 * `success`: true if successfully deleted
 383 * `gid`: gid of the deleted group
 384 * `name`: name of the deleted group
 385 * `status`: "deleted" if successfully deleted
 386 * `wrong users`: empty array
 387
 388 ---
 389
 390 ### GET api/friendica/notifications
 391
 392 Return last 50 [Notifications](help/API-Entities#Notification) for the current user, ordered by date with unseen item on top.
 393
 394 #### Parameters
 395
 396 none
 397
 398 ### POST api/friendica/notifications/seen
 399
 400 Set notification as seen.
 401
 402 #### Parameters
 403
 404 - `id`: id of the notification to set seen
 405
 406 #### Return values
 407
 408 If the note is linked to an item, returns an [Item](help/API-Entities#Item).
 409
 410 Otherwise, a success status is returned:
 411
 412 * `success` (json) | `<status>success</status>` (xml)
 413
 414 ---
 415
 416 ### GET api/friendica/photo
 417
 418 Returns a [Photo](help/API-Entities#Photo).
 419
 420 #### Parameters
 421
 422 * `photo_id`: Resource id of a photo.
 423 * `scale`: (optional) scale value of the photo
 424
 425 Returns data of a picture with the given resource.
 426 If 'scale' isn't provided, returned data include full url to each scale of the photo.
 427 If 'scale' is set, returned data include image data base64 encoded.
 428
 429 possibile scale value are:
 430
 431 * 0: original or max size by server settings
 432 * 1: image with or height at <= 640
 433 * 2: image with or height at <= 320
 434 * 3: thumbnail 160x160
 435 * 4: Profile image at 300x300
 436 * 5: Profile image at 80x80
 437 * 6: Profile image at 48x48
 438
 439 An image used as profile image has only scale 4-6, other images only 0-3
 440
 441 #### Return values
 442
 443 json:
 444
 445 ```json
 446         {
 447                 "id": "photo id",
 448                 "created": "date(YYYY-MM-DD HH:MM:SS)",
 449                 "edited": "date(YYYY-MM-DD HH:MM:SS)",
 450                 "title": "photo title",
 451                 "desc": "photo description",
 452                 "album": "album name",
 453                 "filename": "original file name",
 454                 "type": "mime type",
 455                 "height": "number",
 456                 "width": "number",
 457                 "profile": "1 if is profile photo",
 458                 "link": {
 459                         "<scale>": "url to image",
 460                         ...
 461                 },
 462                 // if 'scale' is set
 463                 "datasize": "size in byte",
 464                 "data": "base64 encoded image data"
 465         }
 466 ```
 467
 468 xml:
 469
 470 ```xml
 471         <photo>
 472                 <id>photo id</id>
 473                 <created>date(YYYY-MM-DD HH:MM:SS)</created>
 474                 <edited>date(YYYY-MM-DD HH:MM:SS)</edited>
 475                 <title>photo title</title>
 476                 <desc>photo description</desc>
 477                 <album>album name</album>
 478                 <filename>original file name</filename>
 479                 <type>mime type</type>
 480                 <height>number</height>
 481                 <width>number</width>
 482                 <profile>1 if is profile photo</profile>
 483                 <links type="array">
 484                 <link type="mime type" scale="scale number" href="image url"/>
 485                         ...
 486                 </links>
 487         </photo>
 488 ```
 489
 490 ### GET api/friendica/photos/list
 491
 492 Returns the API user's [Photo List Items](help/API-Entities#Photo+List+Item).
 493
 494 #### Return values
 495
 496 json:
 497
 498 ```json
 499         [
 500                 {
 501                         "id": "resource_id",
 502                         "album": "album name",
 503                         "filename": "original file name",
 504                         "type": "image mime type",
 505                         "thumb": "url to thumb sized image"
 506                 },
 507                 ...
 508         ]
 509 ```
 510
 511 xml:
 512
 513 ```xml
 514         <photos type="array">
 515                 <photo id="resource_id"
 516                 album="album name"
 517                 filename="original file name"
 518                 type="image mime type">
 519                         "url to thumb sized image"
 520                 </photo>
 521                 ...
 522         </photos>
 523 ```
 524
 525 ### POST api/friendica/photo/create
 526
 527 Alias of [`api/friendica/photo/update`](#POST+api%2Ffriendica%2Fphoto%2Fupdate)
 528
 529 ### POST api/friendica/photo/update
 530
 531 Saves data for the scales 0-2 to database (see above for scale description).
 532 Call adds non-public entries to items table to enable authenticated contacts to comment/like the photo.
 533 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.
 534 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.
 535
 536 #### Parameters
 537
 538 * `photo_id` (optional): if specified the photo with this id will be updated
 539 * `media` (optional): image data as base64, only optional if photo_id is specified (new upload must have media)
 540 * `desc` (optional): description for the photo, updated when photo_id is specified
 541 * `album`: name of the album to be deleted (always necessary)
 542 * `album_new` (optional): can be used to change the album of a single photo if photo_id is specified
 543 * `allow_cid`/`allow_gid`/`deny_cid`/`deny_gid` (optional):
 544     - on create: empty string or omitting = public photo, specify in format ```<x><y><z>``` for private photo
 545         - on update: keys need to be present with empty values for changing a private photo to public
 546
 547 #### Return values
 548
 549 On success:
 550
 551 * new photo uploaded: JSON return with photo data (see [GET api/friendica/photo](#GET+api%2Ffriendica%2Fphoto))
 552 * photo updated - changed photo data: JSON return with photo data (see [GET api/friendica/photo](#GET+api%2Ffriendica%2Fphoto))
 553 * photo updated - changed info: JSON return `{"result": "updated", "message":"Image id 'xyz' has been updated."}`
 554 * photo updated - nothing changed: JSON return `{"result": "cancelled","message": "Nothing to update for image id 'xyz'."}`
 555
 556 On error:
 557
 558 * 403 FORBIDDEN: if not authenticated
 559 * 400 BADREQUEST: "no albumname specified", "no media data submitted", "photo not available", "acl data invalid"
 560 * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
 561                         "image size exceeds Friendica Config setting (uploaded size: x)",
 562                         "unable to process image data",
 563                         "image upload failed",
 564                         "unknown error - uploading photo failed, see Friendica log for more information",
 565                         "unknown error - update photo entry in database failed",
 566                         "unknown error - this error on uploading or updating a photo should never happen"
 567
 568 ### DELETE api/friendica/photo/delete
 569
 570 Deletes a single image with the specified id, is not reversible -> ensure that client is asking user for being sure to do this
 571 Sets item table entries for this photo to deleted = 1.
 572
 573 #### Parameters
 574
 575 * `photo_id`: id of the photo to be deleted
 576
 577 #### Return values
 578
 579 On success:
 580
 581 * JSON return
 582
 583 ```json
 584 {
 585     "result": "deleted",
 586     "message": "photo with id 'xyz' has been deleted from server."
 587 }
 588 ```
 589
 590 On error:
 591
 592 * 403 FORBIDDEN: if not authenticated
 593 * 400 BADREQUEST: "no photo_id specified", "photo not available"
 594 * 500 INTERNALSERVERERROR: "unknown error on deleting photo", "problem with deleting items occurred"
 595
 596 ---
 597
 598 ### POST/DELETE api/friendica/photoalbum/delete
 599
 600 Deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this.
 601
 602 #### Parameters
 603
 604 * `album`: name of the album to be deleted
 605
 606 #### Return values
 607
 608 On success:
 609
 610 * JSON return
 611
 612 ```json
 613 {
 614     "result": "deleted",
 615     "message": "album 'xyz' with all containing photos has been deleted."
 616 }
 617 ```
 618
 619 On error:
 620
 621 * 403 FORBIDDEN: if not authenticated
 622 * 400 BADREQUEST: "no albumname specified", "album not available"
 623 * 500 INTERNALSERVERERROR: "problem with deleting item occured", "unknown error - deleting from database failed"
 624
 625 ### POST/PUT api/friendica/photoalbum/update
 626
 627 Changes the album name to album_new for all photos in album.
 628
 629 #### Parameters
 630
 631 * `album`: name of the album to be updated
 632 * `album_new`: new name of the album
 633
 634 #### Return values
 635
 636 On success:
 637
 638 * JSON return
 639
 640 ```json
 641 {
 642     "result": "updated",
 643     "message":"album 'abc' with all containing photos has been renamed to 'xyz'."
 644 }
 645 ```
 646
 647 On error:
 648
 649 * 403 FORBIDDEN: if not authenticated
 650 * 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available"
 651 * 500 INTERNALSERVERERROR: "unknown error - updating in database failed"
 652
 653 ---
 654
 655 ### GET api/friendica/profile/show
 656
 657 Returns the [Profile](help/API-Entities#Profile) data of the authenticated user.
 658
 659 #### Return values
 660
 661 On success: Array of:
 662
 663 * `global_dir`: URL of the global directory set in server settings
 664 * `friendica_owner`: user data of the authenticated user
 665 * `profiles`: array of the profile data
 666
 667 On error:
 668 HTTP 403 Forbidden: when no authentication was provided
 669 HTTP 400 Bad Request: if given profile_id is not in the database or is not assigned to the authenticated user
 670
 671 General description of profile data in API returns:
 672 - hide_friends: true if friends are hidden
 673 - profile_photo
 674 - profile_thumb
 675 - publish: true if published on the server's local directory
 676 - net_publish: true if published to global_dir
 677 - fullname
 678 - date_of_birth
 679 - description
 680 - xmpp
 681 - homepage
 682 - address
 683 - locality
 684 - region
 685 - postal_code
 686 - country
 687 - pub_keywords
 688 - custom_fields: list of public custom fields
 689
 690 ---
 691
 692 ### GET api/friendica/remoteauth
 693
 694 Similar as /redir, redirects to `url` after DFRN authentication.
 695
 696 #### Parameters
 697
 698 - `c_url`: url of remote contact to auth to
 699 - `url`: string, url to redirect after auth
 700
 701 ## Deprecated endpoints
 702
 703 - POST api/statuses/mediap