Friendica Communications Platform (please note that this is a clone of the repository at github, issues are handled there) https://friendi.ca
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

api.md 32KB

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