doc/api.md

   1 Friendica API\r
   2 ===\r
   3 \r
   4 * [Home](help)\r
   5 \r
   6 The Friendica API aims to be compatible to the [GNU Social API](http://wiki.gnusocial.de/gnusocial:api) and the [Twitter API](https://dev.twitter.com/rest/public).\r
   7 \r
   8 Please refer to the linked documentation for further information.\r
   9 \r
  10 ## Implemented API calls\r
  11 \r
  12 ### General\r
  13 #### HTTP Method\r
  14 \r
  15 API endpoints can restrict the method used to request them.\r
  16 Using an invalid method results in HTTP error 405 "Method Not Allowed".\r
  17 \r
  18 In this document, the required method is listed after the endpoint name. "*" means every method can be used.\r
  19 \r
  20 #### Auth\r
  21 \r
  22 Friendica supports basic http auth and OAuth 1 to authenticate the user to the api.\r
  23 \r
  24 OAuth settings can be added by the user in web UI under /settings/oauth/\r
  25 \r
  26 In this document, endpoints which requires auth are marked with "AUTH" after endpoint name\r
  27 \r
  28 #### Unsupported parameters\r
  29 * cursor: Not implemented in GNU Social\r
  30 * trim_user: Not implemented in GNU Social\r
  31 * contributor_details: Not implemented in GNU Social\r
  32 * place_id: Not implemented in GNU Social\r
  33 * display_coordinates: Not implemented in GNU Social\r
  34 * include_rts: To-Do\r
  35 * include_my_retweet: Retweets in Friendica are implemented in a different way\r
  36 \r
  37 #### Different behaviour\r
  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.\r
  39 * include_entities: Default is "false". If set to "true" then the plain text is formatted so that links are having descriptions.\r
  40 \r
  41 #### Return values\r
  42 * cid: Contact id of the user (important for "contact_allow" and "contact_deny")\r
  43 * network: network of the user\r
  44 \r
  45 #### Errors\r
  46 When an error occour in API call, an HTTP error code is returned, with an error message\r
  47 Usually:\r
  48 - 400 Bad Request: if parameter are missing or items can't be found\r
  49 - 403 Forbidden: if authenticated user is missing\r
  50 - 405 Method Not Allowed: if API was called with invalid method, eg. GET when API require POST\r
  51 - 501 Not Implemented: if requested API doesn't exists\r
  52 - 500 Internal Server Error: on other error contitions\r
  53 \r
  54 Error body is\r
  55 \r
  56 json:\r
  57 ```\r
  58         {\r
  59                 "error": "Specific error message",\r
  60                 "request": "API path requested",\r
  61                 "code": "HTTP error code"\r
  62         }\r
  63 ```\r
  64 \r
  65 xml:\r
  66 ```\r
  67         <status>\r
  68                 <error>Specific error message</error>\r
  69                 <request>API path requested</request>\r
  70                 <code>HTTP error code</code>\r
  71         </status>\r
  72 ```\r
  73 \r
  74 ---\r
  75 ### account/rate_limit_status (*; AUTH)\r
  76 \r
  77 ---\r
  78 ### account/verify_credentials (*; AUTH)\r
  79 #### Parameters\r
  80 \r
  81 * skip_status: Don't show the "status" field. (Default: false)\r
  82 * include_entities: "true" shows entities for pictures and links (Default: false)\r
  83 \r
  84 ---\r
  85 ### conversation/show (*; AUTH)\r
  86 Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.\r
  87 \r
  88 #### Parameter\r
  89 * id: id of the post\r
  90 * count: Items per page (default: 20)\r
  91 * page: page number\r
  92 * since_id: minimal id\r
  93 * max_id: maximum id\r
  94 * include_entities: "true" shows entities for pictures and links (Default: false)\r
  95 \r
  96 #### Unsupported parameters\r
  97 * include_rts\r
  98 * trim_user\r
  99 * contributor_details\r
 100 \r
 101 ---\r
 102 ### direct_messages (*; AUTH)\r
 103 #### Parameters\r
 104 * count: Items per page (default: 20)\r
 105 * page: page number\r
 106 * since_id: minimal id\r
 107 * max_id: maximum id\r
 108 * getText: Defines the format of the status field. Can be "html" or "plain"\r
 109 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 110 * friendica_verbose: "true" enables different error returns (default: "false")\r
 111 \r
 112 #### Unsupported parameters\r
 113 * skip_status\r
 114 \r
 115 ---\r
 116 ### direct_messages/all (*; AUTH)\r
 117 #### Parameters\r
 118 * count: Items per page (default: 20)\r
 119 * page: page number\r
 120 * since_id: minimal id\r
 121 * max_id: maximum id\r
 122 * getText: Defines the format of the status field. Can be "html" or "plain"\r
 123 * friendica_verbose: "true" enables different error returns (default: "false")\r
 124 \r
 125 ---\r
 126 ### direct_messages/conversation (*; AUTH)\r
 127 Shows all direct messages of a conversation\r
 128 #### Parameters\r
 129 * count: Items per page (default: 20)\r
 130 * page: page number\r
 131 * since_id: minimal id\r
 132 * max_id: maximum id\r
 133 * getText: Defines the format of the status field. Can be "html" or "plain"\r
 134 * uri: URI of the conversation\r
 135 * friendica_verbose: "true" enables different error returns (default: "false")\r
 136 \r
 137 ---\r
 138 ### direct_messages/sent (*; AUTH)\r
 139 #### Parameters\r
 140 * count: Items per page (default: 20)\r
 141 * page: page number\r
 142 * since_id: minimal id\r
 143 * max_id: maximum id\r
 144 * getText: Defines the format of the status field. Can be "html" or "plain"\r
 145 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 146 * friendica_verbose: "true" enables different error returns (default: "false")\r
 147 \r
 148 ---\r
 149 ### direct_messages/new (POST,PUT; AUTH)\r
 150 #### Parameters\r
 151 * user_id: id of the user\r
 152 * screen_name: screen name (for technical reasons, this value is not unique!)\r
 153 * text: The message\r
 154 * replyto: ID of the replied direct message\r
 155 * title: Title of the direct message\r
 156 \r
 157 ---\r
 158 ### direct_messages/destroy (POST,DELETE; AUTH)\r
 159 #### Parameters\r
 160 * id: id of the message to be deleted\r
 161 * include_entities: optional, currently not yet implemented\r
 162 * friendica_parenturi: optional, can be used for increased safety to delete only intended messages\r
 163 * friendica_verbose: "true" enables different error returns (default: "false")\r
 164 \r
 165 #### Return values\r
 166 \r
 167 On success:\r
 168 * JSON return as defined for Twitter API not yet implemented\r
 169 * on friendica_verbose=true: JSON return {"result":"ok","message":"message deleted"}\r
 170 \r
 171 On error:\r
 172 HTTP 400 BadRequest\r
 173 * on friendica_verbose=true: different JSON returns {"result":"error","message":"xyz"}\r
 174 \r
 175 ---\r
 176 ### externalprofile/show (*)\r
 177 #### Parameters\r
 178 * profileurl: profile url\r
 179 \r
 180 ---\r
 181 ### favorites (*; AUTH)\r
 182 #### Parameters\r
 183 * count: Items per page (default: 20)\r
 184 * page: page number\r
 185 * since_id: minimal id\r
 186 * max_id: maximum id\r
 187 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 188 \r
 189 #### Unsupported parameters\r
 190 * user_id\r
 191 * screen_name\r
 192 \r
 193 Favorites aren't displayed to other users, so "user_id" and "screen_name" are unsupported.\r
 194 Set this values will result in an empty array.\r
 195 \r
 196 ---\r
 197 ### favorites/create (POST,PUT; AUTH)\r
 198 #### Parameters\r
 199 * id\r
 200 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 201 \r
 202 ---\r
 203 ### favorites/destroy (POST,DELETE; AUTH)\r
 204 #### Parameters\r
 205 * id\r
 206 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 207 \r
 208 ---\r
 209 ### followers/ids (*; AUTH)\r
 210 #### Parameters\r
 211 * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)\r
 212 \r
 213 #### Unsupported parameters\r
 214 * user_id\r
 215 * screen_name\r
 216 * cursor\r
 217 \r
 218 Friendica doesn't allow showing followers of other users.\r
 219 \r
 220 ---\r
 221 ### friends/ids (*; AUTH)\r
 222 #### Parameters\r
 223 * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)\r
 224 \r
 225 #### Unsupported parameters\r
 226 * user_id\r
 227 * screen_name\r
 228 * cursor\r
 229 \r
 230 Friendica doesn't allow showing friends of other users.\r
 231 \r
 232 ---\r
 233 ### help/test (*)\r
 234 \r
 235 ---\r
 236 ### media/upload (POST,PUT; AUTH)\r
 237 #### Parameters\r
 238 * media: image data\r
 239 \r
 240 ---\r
 241 ### oauth/request_token (*)\r
 242 #### Parameters\r
 243 * oauth_callback\r
 244 \r
 245 #### Unsupported parameters\r
 246 * x_auth_access_type\r
 247 \r
 248 ---\r
 249 ### oauth/access_token (*)\r
 250 #### Parameters\r
 251 * oauth_verifier\r
 252 \r
 253 #### Unsupported parameters\r
 254 * x_auth_password\r
 255 * x_auth_username\r
 256 * x_auth_mode\r
 257 \r
 258 ---\r
 259 ### statuses/destroy (POST,DELETE; AUTH)\r
 260 #### Parameters\r
 261 * id: message number\r
 262 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 263 \r
 264 #### Unsupported parameters\r
 265 * trim_user\r
 266 \r
 267 ---\r
 268 ### statuses/followers (*; AUTH)\r
 269 \r
 270 #### Parameters\r
 271 \r
 272 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 273 \r
 274 ---\r
 275 ### statuses/friends (*; AUTH)\r
 276 \r
 277 #### Parameters\r
 278 \r
 279 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 280 \r
 281 ---\r
 282 ### statuses/friends_timeline (*; AUTH)\r
 283 #### Parameters\r
 284 * count: Items per page (default: 20)\r
 285 * page: page number\r
 286 * since_id: minimal id\r
 287 * max_id: maximum id\r
 288 * exclude_replies: don't show replies (default: false)\r
 289 * conversation_id: Shows all statuses of a given conversation.\r
 290 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 291 \r
 292 #### Unsupported parameters\r
 293 * include_rts\r
 294 * trim_user\r
 295 * contributor_details\r
 296 \r
 297 ---\r
 298 ### statuses/home_timeline (*; AUTH)\r
 299 #### Parameters\r
 300 * count: Items per page (default: 20)\r
 301 * page: page number\r
 302 * since_id: minimal id\r
 303 * max_id: maximum id\r
 304 * exclude_replies: don't show replies (default: false)\r
 305 * conversation_id: Shows all statuses of a given conversation.\r
 306 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 307 \r
 308 #### Unsupported parameters\r
 309 * include_rts\r
 310 * trim_user\r
 311 * contributor_details\r
 312 \r
 313 ---\r
 314 ### statuses/mentions (*; AUTH)\r
 315 #### Parameters\r
 316 * count: Items per page (default: 20)\r
 317 * page: page number\r
 318 * since_id: minimal id\r
 319 * max_id: maximum id\r
 320 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 321 \r
 322 #### Unsupported parameters\r
 323 * include_rts\r
 324 * trim_user\r
 325 * contributor_details\r
 326 \r
 327 ---\r
 328 ### statuses/public_timeline (*; AUTH)\r
 329 #### Parameters\r
 330 * count: Items per page (default: 20)\r
 331 * page: page number\r
 332 * since_id: minimal id\r
 333 * max_id: maximum id\r
 334 * exclude_replies: don't show replies (default: false)\r
 335 * conversation_id: Shows all statuses of a given conversation.\r
 336 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 337 \r
 338 #### Unsupported parameters\r
 339 * trim_user\r
 340 \r
 341 ---\r
 342 ### statuses/replies (*; AUTH)\r
 343 #### Parameters\r
 344 * count: Items per page (default: 20)\r
 345 * page: page number\r
 346 * since_id: minimal id\r
 347 * max_id: maximum id\r
 348 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 349 \r
 350 #### Unsupported parameters\r
 351 * include_rts\r
 352 * trim_user\r
 353 * contributor_details\r
 354 \r
 355 ---\r
 356 ### statuses/retweet (POST,PUT; AUTH)\r
 357 #### Parameters\r
 358 * id: message number\r
 359 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 360 \r
 361 #### Unsupported parameters\r
 362 * trim_user\r
 363 \r
 364 ---\r
 365 ### statuses/show (*; AUTH)\r
 366 #### Parameters\r
 367 * id: message number\r
 368 * conversation: if set to "1" show all messages of the conversation with the given id\r
 369 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 370 \r
 371 #### Unsupported parameters\r
 372 * include_my_retweet\r
 373 * trim_user\r
 374 \r
 375 ---\r
 376 ### statuses/update, statuses/update_with_media\r
 377 #### Parameters\r
 378 * title: Title of the status\r
 379 * status: Status in text format\r
 380 * htmlstatus: Status in HTML format\r
 381 * in_reply_to_status_id\r
 382 * lat: latitude\r
 383 * long: longitude\r
 384 * media: image data\r
 385 * source: Application name\r
 386 * group_allow\r
 387 * contact_allow\r
 388 * group_deny\r
 389 * contact_deny\r
 390 * network\r
 391 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 392 * media_ids: (By now only a single value, no array)\r
 393 \r
 394 #### Unsupported parameters\r
 395 * trim_user\r
 396 * place_id\r
 397 * display_coordinates\r
 398 \r
 399 ---\r
 400 ### statuses/user_timeline (*; AUTH)\r
 401 #### Parameters\r
 402 * user_id: id of the user\r
 403 * screen_name: screen name (for technical reasons, this value is not unique!)\r
 404 * count: Items per page (default: 20)\r
 405 * page: page number\r
 406 * since_id: minimal id\r
 407 * max_id: maximum id\r
 408 * exclude_replies: don't show replies (default: false)\r
 409 * conversation_id: Shows all statuses of a given conversation.\r
 410 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 411 \r
 412 #### Unsupported parameters\r
 413 \r
 414 * include_rts\r
 415 * trim_user\r
 416 * contributor_details\r
 417 \r
 418 ---\r
 419 ### statusnet/config (*)\r
 420 \r
 421 ---\r
 422 ### statusnet/conversation (*; AUTH)\r
 423 It shows all direct answers (excluding the original post) to a given id.\r
 424 \r
 425 #### Parameter\r
 426 * id: id of the post\r
 427 * count: Items per page (default: 20)\r
 428 * page: page number\r
 429 * since_id: minimal id\r
 430 * max_id: maximum id\r
 431 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 432 \r
 433 ---\r
 434 ### statusnet/version (*)\r
 435 \r
 436 #### Unsupported parameters\r
 437 * user_id\r
 438 * screen_name\r
 439 * cursor\r
 440 \r
 441 Friendica doesn't allow showing followers of other users.\r
 442 \r
 443 ---\r
 444 ### users/search (*)\r
 445 #### Parameters\r
 446 * q: name of the user\r
 447 \r
 448 #### Unsupported parameters\r
 449 * page\r
 450 * count\r
 451 * include_entities\r
 452 \r
 453 ---\r
 454 ### users/show (*)\r
 455 #### Parameters\r
 456 * user_id: id of the user\r
 457 * screen_name: screen name (for technical reasons, this value is not unique!)\r
 458 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 459 \r
 460 #### Unsupported parameters\r
 461 * user_id\r
 462 * screen_name\r
 463 * cursor\r
 464 \r
 465 Friendica doesn't allow showing friends of other users.\r
 466 \r
 467 \r
 468 ## Implemented API calls (not compatible with other APIs)\r
 469 \r
 470 \r
 471 ---\r
 472 ### friendica/activity/<verb>\r
 473 #### parameters\r
 474 * id: item id\r
 475 \r
 476 Add or remove an activity from an item.\r
 477 'verb' can be one of:\r
 478 \r
 479 - like\r
 480 - dislike\r
 481 - attendyes\r
 482 - attendno\r
 483 - attendmaybe\r
 484 \r
 485 To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"\r
 486 Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".\r
 487 Attend verbs should be used only with event-related items (there is no check at the moment)\r
 488 \r
 489 #### Return values\r
 490 \r
 491 On success:\r
 492 json\r
 493 ```"ok"```\r
 494 \r
 495 xml\r
 496 ```<ok>true</ok>```\r
 497 \r
 498 On error:\r
 499 HTTP 400 BadRequest\r
 500 \r
 501 ---\r
 502 ### friendica/group_show (*; AUTH)\r
 503 Return all or a specified group of the user with the containing contacts as array.\r
 504 \r
 505 #### Parameters\r
 506 * gid: optional, if not given, API returns all groups of the user\r
 507 \r
 508 #### Return values\r
 509 Array of:\r
 510 \r
 511 * name: name of the group\r
 512 * gid: id of the group\r
 513 * user: array of group members (return from api_get_user() function for each member)\r
 514 \r
 515 \r
 516 ---\r
 517 ### friendica/group_delete (POST,DELETE; AUTH)\r
 518 delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted.\r
 519 \r
 520 #### Parameters\r
 521 * gid: id of the group to be deleted\r
 522 * name: name of the group to be deleted\r
 523 \r
 524 #### Return values\r
 525 Array of:\r
 526 \r
 527 * success: true if successfully deleted\r
 528 * gid: gid of the deleted group\r
 529 * name: name of the deleted group\r
 530 * status: „deleted“ if successfully deleted\r
 531 * wrong users: empty array\r
 532 \r
 533 \r
 534 ---\r
 535 ### friendica/group_create (POST,PUT; AUTH)\r
 536 Create the group with the posted array of contacts as members.\r
 537 \r
 538 #### Parameters\r
 539 * name: name of the group to be created\r
 540 \r
 541 #### POST data\r
 542 JSON data as Array like the result of "users/group_show":\r
 543 \r
 544 * gid\r
 545 * name\r
 546 * array of users\r
 547 \r
 548 #### Return values\r
 549 Array of:\r
 550 \r
 551 * success: true if successfully created or reactivated\r
 552 * gid: gid of the created group\r
 553 * name: name of the created group\r
 554 * status: „missing user“ | „reactivated“ | „ok“\r
 555 * wrong users: array of users, which were not available in the contact table\r
 556 \r
 557 \r
 558 ---\r
 559 ### friendica/group_update (POST)\r
 560 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).\r
 561 \r
 562 #### Parameters\r
 563 * gid: id of the group to be changed\r
 564 * name: name of the group to be changed\r
 565 \r
 566 #### POST data\r
 567 JSON data as array like the result of „users/group_show“:\r
 568 \r
 569 * gid\r
 570 * name\r
 571 * array of users\r
 572 \r
 573 #### Return values\r
 574 Array of:\r
 575 \r
 576 * success: true if successfully updated\r
 577 * gid: gid of the changed group\r
 578 * name: name of the changed group\r
 579 * status: „missing user“ | „ok“\r
 580 * wrong users: array of users, which were not available in the contact table\r
 581 \r
 582 \r
 583 \r
 584 ---\r
 585 ### friendica/notifications (GET)\r
 586 Return last 50 notification for current user, ordered by date with unseen item on top\r
 587 \r
 588 #### Parameters\r
 589 none\r
 590 \r
 591 #### Return values\r
 592 Array of:\r
 593 \r
 594 * id: id of the note\r
 595 * type: type of notification as int (see NOTIFY_* constants in boot.php)\r
 596 * name: full name of the contact subject of the note\r
 597 * url: contact's profile url\r
 598 * photo: contact's profile photo\r
 599 * date: datetime string of the note\r
 600 * timestamp: timestamp of the node\r
 601 * date_rel: relative date of the note (eg. "1 hour ago")\r
 602 * msg: note message in bbcode\r
 603 * msg_html: note message in html\r
 604 * msg_plain: note message in plain text\r
 605 * link: link to note\r
 606 * seen: seen state: 0 or 1\r
 607 \r
 608 \r
 609 ---\r
 610 ### friendica/notifications/seen (POST)\r
 611 Set note as seen, returns item object if possible\r
 612 \r
 613 #### Parameters\r
 614 id: id of the note to set seen\r
 615 \r
 616 #### Return values\r
 617 If the note is linked to an item, the item is returned, just like one of the "statuses/*_timeline" api.\r
 618 \r
 619 If the note is not linked to an item, a success status is returned:\r
 620 \r
 621 * "success" (json) | "&lt;status&gt;success&lt;/status&gt;" (xml)\r
 622 \r
 623 \r
 624 ---\r
 625 ### friendica/photo (*; AUTH)\r
 626 #### Parameters\r
 627 * photo_id: Resource id of a photo.\r
 628 * scale: (optional) scale value of the photo\r
 629 \r
 630 Returns data of a picture with the given resource.\r
 631 If 'scale' isn't provided, returned data include full url to each scale of the photo.\r
 632 If 'scale' is set, returned data include image data base64 encoded.\r
 633 \r
 634 possibile scale value are:\r
 635 \r
 636 * 0: original or max size by server settings\r
 637 * 1: image with or height at <= 640\r
 638 * 2: image with or height at <= 320\r
 639 * 3: thumbnail 160x160\r
 640 * 4: Profile image at 175x175\r
 641 * 5: Profile image at 80x80\r
 642 * 6: Profile image at 48x48\r
 643 \r
 644 An image used as profile image has only scale 4-6, other images only 0-3\r
 645 \r
 646 #### Return values\r
 647 \r
 648 json\r
 649 ```\r
 650         {\r
 651                 "id": "photo id"\r
 652                 "created": "date(YYYY-MM-GG HH:MM:SS)",\r
 653                 "edited": "date(YYYY-MM-GG HH:MM:SS)",\r
 654                 "title": "photo title",\r
 655                 "desc": "photo description",\r
 656                 "album": "album name",\r
 657                 "filename": "original file name",\r
 658                 "type": "mime type",\r
 659                 "height": "number",\r
 660                 "width": "number",\r
 661                 "profile": "1 if is profile photo",\r
 662                 "link": {\r
 663                         "<scale>": "url to image"\r
 664                         ...\r
 665                 },\r
 666                 // if 'scale' is set\r
 667                 "datasize": "size in byte",\r
 668                 "data": "base64 encoded image data"\r
 669         }\r
 670 ```\r
 671 \r
 672 xml\r
 673 ```\r
 674         <photo>\r
 675                 <id>photo id</id>\r
 676                 <created>date(YYYY-MM-GG HH:MM:SS)</created>\r
 677                 <edited>date(YYYY-MM-GG HH:MM:SS)</edited>\r
 678                 <title>photo title</title>\r
 679                 <desc>photo description</desc>\r
 680                 <album>album name</album>\r
 681                 <filename>original file name</filename>\r
 682                 <type>mime type</type>\r
 683                 <height>number</height>\r
 684                 <width>number</width>\r
 685                 <profile>1 if is profile photo</profile>\r
 686                 <links type="array">\r
 687                 <link type="mime type" scale="scale number" href="image url"/>\r
 688                         ...\r
 689                 </links>\r
 690         </photo>\r
 691 ```\r
 692 \r
 693 ---\r
 694 ### friendica/photos/list (*; AUTH)\r
 695 \r
 696 Returns a list of all photo resources of the logged in user.\r
 697 \r
 698 #### Return values\r
 699 \r
 700 json\r
 701 ```\r
 702         [\r
 703                 {\r
 704                         id: "resource_id",\r
 705                         album: "album name",\r
 706                         filename: "original file name",\r
 707                         type: "image mime type",\r
 708                         thumb: "url to thumb sized image"\r
 709                 },\r
 710                 ...\r
 711         ]\r
 712 ```\r
 713 \r
 714 xml\r
 715 ```\r
 716         <photos type="array">\r
 717                 <photo id="resource_id"\r
 718                 album="album name"\r
 719                 filename="original file name"\r
 720                 type="image mime type">\r
 721                         "url to thumb sized image"\r
 722                 </photo>\r
 723                 ...\r
 724         </photos>\r
 725 ```\r
 726 \r
 727 ---\r
 728 ### friendica/direct_messages_setseen (GET; AUTH)\r
 729 #### Parameters\r
 730 * id: id of the message to be updated as seen\r
 731 \r
 732 #### Return values\r
 733 \r
 734 On success:\r
 735 * JSON return {"result":"ok","message":"message set to seen"}\r
 736 \r
 737 On error:\r
 738 * different JSON returns {"result":"error","message":"xyz"}\r
 739 \r
 740 ---\r
 741 ### friendica/direct_messages_search (GET; AUTH)\r
 742 #### Parameters\r
 743 * searchstring: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored)\r
 744 \r
 745 #### Return values\r
 746 Returns only tested with JSON, XML might work as well.\r
 747 \r
 748 On success:\r
 749 * JSON return {"success":"true","search_results": array of found messages}\r
 750 * JSOn return {"success":"false","search_results":"nothing found"}\r
 751 \r
 752 On error:\r
 753 * different JSON returns {"result":"error","message":"searchstring not specified"}\r
 754 \r
 755 ---\r
 756 ### friendica/profile/show (GET; AUTH)\r
 757 show data of all profiles or a single profile of the authenticated user\r
 758 \r
 759 #### Parameters\r
 760 * profile_id: id of the profile to be returned (optional, if omitted all profiles are returned by default)\r
 761 \r
 762 #### Return values\r
 763 On success: Array of:\r
 764 \r
 765 * multi_profiles: true if user has activated multi_profiles\r
 766 * global_dir: URL of the global directory set in server settings\r
 767 * friendica_owner: user data of the authenticated user\r
 768 * profiles: array of the profile data\r
 769 \r
 770 On error: \r
 771 HTTP 403 Forbidden: when no authentication provided\r
 772 HTTP 400 Bad Request: if given profile_id is not in db or not assigned to authenticated user\r
 773 \r
 774 General description of profile data in API returns:\r
 775 * profile_id\r
 776 * profile_name\r
 777 * is_default: true if this is the public profile\r
 778 * hide_friends: true if friends are hidden\r
 779 * profile_photo\r
 780 * profile_thumb\r
 781 * publish: true if published on the server's local directory\r
 782 * net_publish: true if published to global_dir\r
 783 * description ... homepage: different data fields from 'profile' table in database\r
 784 * users: array with the users allowed to view this profile (empty if is_default=true)\r
 785 \r
 786 \r
 787 ---\r
 788 ## Not Implemented API calls\r
 789 The following API calls are implemented in GNU Social but not in Friendica: (incomplete)\r
 790 \r
 791 * statuses/retweets_of_me\r
 792 * friendships/create\r
 793 * friendships/destroy\r
 794 * friendships/exists\r
 795 * friendships/show\r
 796 * account/update_profile_background_image\r
 797 * account/update_profile_image\r
 798 * blocks/create\r
 799 * blocks/destroy\r
 800 \r
 801 The following API calls from the Twitter API aren't implemented neither in Friendica nor in GNU Social:\r
 802 \r
 803 * statuses/mentions_timeline\r
 804 * statuses/retweets/:id\r
 805 * statuses/oembed\r
 806 * statuses/retweeters/ids\r
 807 * statuses/lookup\r
 808 * direct_messages/show\r
 809 * search/tweets\r
 810 * friendships/no_retweets/ids\r
 811 * friendships/incoming\r
 812 * friendships/outgoing\r
 813 * friendships/update\r
 814 * friends/list\r
 815 * friendships/lookup\r
 816 * account/settings\r
 817 * account/update_delivery_device\r
 818 * account/update_profile\r
 819 * account/update_profile_background_image\r
 820 * account/update_profile_image\r
 821 * blocks/list\r
 822 * blocks/ids\r
 823 * users/lookup\r
 824 * users/show\r
 825 * users/search\r
 826 * account/remove_profile_banner\r
 827 * account/update_profile_banner\r
 828 * users/profile_banner\r
 829 * mutes/users/create\r
 830 * mutes/users/destroy\r
 831 * mutes/users/ids\r
 832 * mutes/users/list\r
 833 * users/suggestions/:slug\r
 834 * users/suggestions\r
 835 * users/suggestions/:slug/members\r
 836 * favorites/list\r
 837 * lists/list\r
 838 * lists/statuses\r
 839 * lists/members/destroy\r
 840 * lists/memberships\r
 841 * lists/subscribers\r
 842 * lists/subscribers/create\r
 843 * lists/subscribers/show\r
 844 * lists/subscribers/destroy\r
 845 * lists/members/create_all\r
 846 * lists/members/show\r
 847 * lists/members\r
 848 * lists/members/create\r
 849 * lists/destroy\r
 850 * lists/update\r
 851 * lists/create\r
 852 * lists/show\r
 853 * lists/subscriptions\r
 854 * lists/members/destroy_all\r
 855 * lists/ownerships\r
 856 * saved_searches/list\r
 857 * saved_searches/show/:id\r
 858 * saved_searches/create\r
 859 * saved_searches/destroy/:id\r
 860 * geo/id/:place_id\r
 861 * geo/reverse_geocode\r
 862 * geo/search\r
 863 * geo/place\r
 864 * trends/place\r
 865 * trends/available\r
 866 * help/configuration\r
 867 * help/languages\r
 868 * help/privacy\r
 869 * help/tos\r
 870 * trends/closest\r
 871 * users/report_spam\r
 872 \r
 873 ---\r
 874 \r
 875 ---\r
 876 \r
 877 ## Usage Examples\r
 878 ### BASH / cURL\r
 879 Betamax has documentated some example API usage from a [bash script](https://en.wikipedia.org/wiki/Bash_(Unix_shell) employing [curl](https://en.wikipedia.org/wiki/CURL) (see [his posting](https://betamax65.de/display/betamax65/43539)).\r
 880 \r
 881 /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"\r
 882 \r
 883 ### Python\r
 884 The [RSStoFriedika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python. The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.\r
 885 \r
 886 def tweet(server, message, group_allow=None):\r
 887 url = server + '/api/statuses/update'\r
 888 urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))\r
 889 \r
 890 There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.\r