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