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