docker_remote_api_v1.4.rst 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176
  1. :title: Remote API v1.4
  2. :description: API Documentation for Docker
  3. :keywords: API, Docker, rcli, REST, documentation
  4. :orphan:
  5. ======================
  6. Docker Remote API v1.4
  7. ======================
  8. .. contents:: Table of Contents
  9. 1. Brief introduction
  10. =====================
  11. - The Remote API is replacing rcli
  12. - Default port in the docker daemon is 4243
  13. - The API tends to be REST, but for some complex commands, like attach or pull, the HTTP connection is hijacked to transport stdout stdin and stderr
  14. 2. Endpoints
  15. ============
  16. 2.1 Containers
  17. --------------
  18. List containers
  19. ***************
  20. .. http:get:: /containers/json
  21. List containers
  22. **Example request**:
  23. .. sourcecode:: http
  24. GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1
  25. **Example response**:
  26. .. sourcecode:: http
  27. HTTP/1.1 200 OK
  28. Content-Type: application/json
  29. [
  30. {
  31. "Id": "8dfafdbc3a40",
  32. "Image": "ubuntu:latest",
  33. "Command": "echo 1",
  34. "Created": 1367854155,
  35. "Status": "Exit 0",
  36. "Ports":"",
  37. "SizeRw":12288,
  38. "SizeRootFs":0
  39. },
  40. {
  41. "Id": "9cd87474be90",
  42. "Image": "ubuntu:latest",
  43. "Command": "echo 222222",
  44. "Created": 1367854155,
  45. "Status": "Exit 0",
  46. "Ports":"",
  47. "SizeRw":12288,
  48. "SizeRootFs":0
  49. },
  50. {
  51. "Id": "3176a2479c92",
  52. "Image": "centos:latest",
  53. "Command": "echo 3333333333333333",
  54. "Created": 1367854154,
  55. "Status": "Exit 0",
  56. "Ports":"",
  57. "SizeRw":12288,
  58. "SizeRootFs":0
  59. },
  60. {
  61. "Id": "4cb07b47f9fb",
  62. "Image": "fedora:latest",
  63. "Command": "echo 444444444444444444444444444444444",
  64. "Created": 1367854152,
  65. "Status": "Exit 0",
  66. "Ports":"",
  67. "SizeRw":12288,
  68. "SizeRootFs":0
  69. }
  70. ]
  71. :query all: 1/True/true or 0/False/false, Show all containers. Only running containers are shown by default
  72. :query limit: Show ``limit`` last created containers, include non-running ones.
  73. :query since: Show only containers created since Id, include non-running ones.
  74. :query before: Show only containers created before Id, include non-running ones.
  75. :query size: 1/True/true or 0/False/false, Show the containers sizes
  76. :statuscode 200: no error
  77. :statuscode 400: bad parameter
  78. :statuscode 500: server error
  79. Create a container
  80. ******************
  81. .. http:post:: /containers/create
  82. Create a container
  83. **Example request**:
  84. .. sourcecode:: http
  85. POST /containers/create HTTP/1.1
  86. Content-Type: application/json
  87. {
  88. "Hostname":"",
  89. "User":"",
  90. "Memory":0,
  91. "MemorySwap":0,
  92. "AttachStdin":false,
  93. "AttachStdout":true,
  94. "AttachStderr":true,
  95. "PortSpecs":null,
  96. "Privileged": false,
  97. "Tty":false,
  98. "OpenStdin":false,
  99. "StdinOnce":false,
  100. "Env":null,
  101. "Cmd":[
  102. "date"
  103. ],
  104. "Dns":null,
  105. "Image":"ubuntu",
  106. "Volumes":{},
  107. "VolumesFrom":"",
  108. "WorkingDir":""
  109. }
  110. **Example response**:
  111. .. sourcecode:: http
  112. HTTP/1.1 201 OK
  113. Content-Type: application/json
  114. {
  115. "Id":"e90e34656806"
  116. "Warnings":[]
  117. }
  118. :jsonparam config: the container's configuration
  119. :statuscode 201: no error
  120. :statuscode 404: no such container
  121. :statuscode 406: impossible to attach (container not running)
  122. :statuscode 500: server error
  123. Inspect a container
  124. *******************
  125. .. http:get:: /containers/(id)/json
  126. Return low-level information on the container ``id``
  127. **Example request**:
  128. .. sourcecode:: http
  129. GET /containers/4fa6e0f0c678/json HTTP/1.1
  130. **Example response**:
  131. .. sourcecode:: http
  132. HTTP/1.1 200 OK
  133. Content-Type: application/json
  134. {
  135. "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2",
  136. "Created": "2013-05-07T14:51:42.041847+02:00",
  137. "Path": "date",
  138. "Args": [],
  139. "Config": {
  140. "Hostname": "4fa6e0f0c678",
  141. "User": "",
  142. "Memory": 0,
  143. "MemorySwap": 0,
  144. "AttachStdin": false,
  145. "AttachStdout": true,
  146. "AttachStderr": true,
  147. "PortSpecs": null,
  148. "Tty": false,
  149. "OpenStdin": false,
  150. "StdinOnce": false,
  151. "Env": null,
  152. "Cmd": [
  153. "date"
  154. ],
  155. "Dns": null,
  156. "Image": "ubuntu",
  157. "Volumes": {},
  158. "VolumesFrom": "",
  159. "WorkingDir":""
  160. },
  161. "State": {
  162. "Running": false,
  163. "Pid": 0,
  164. "ExitCode": 0,
  165. "StartedAt": "2013-05-07T14:51:42.087658+02:01360",
  166. "Ghost": false
  167. },
  168. "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
  169. "NetworkSettings": {
  170. "IpAddress": "",
  171. "IpPrefixLen": 0,
  172. "Gateway": "",
  173. "Bridge": "",
  174. "PortMapping": null
  175. },
  176. "SysInitPath": "/home/kitty/go/src/github.com/dotcloud/docker/bin/docker",
  177. "ResolvConfPath": "/etc/resolv.conf",
  178. "Volumes": {}
  179. }
  180. :statuscode 200: no error
  181. :statuscode 404: no such container
  182. :statuscode 409: conflict between containers and images
  183. :statuscode 500: server error
  184. List processes running inside a container
  185. *****************************************
  186. .. http:get:: /containers/(id)/top
  187. List processes running inside the container ``id``
  188. **Example request**:
  189. .. sourcecode:: http
  190. GET /containers/4fa6e0f0c678/top HTTP/1.1
  191. **Example response**:
  192. .. sourcecode:: http
  193. HTTP/1.1 200 OK
  194. Content-Type: application/json
  195. {
  196. "Titles":[
  197. "USER",
  198. "PID",
  199. "%CPU",
  200. "%MEM",
  201. "VSZ",
  202. "RSS",
  203. "TTY",
  204. "STAT",
  205. "START",
  206. "TIME",
  207. "COMMAND"
  208. ],
  209. "Processes":[
  210. ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"],
  211. ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"]
  212. ]
  213. }
  214. :query ps_args: ps arguments to use (eg. aux)
  215. :statuscode 200: no error
  216. :statuscode 404: no such container
  217. :statuscode 500: server error
  218. Inspect changes on a container's filesystem
  219. *******************************************
  220. .. http:get:: /containers/(id)/changes
  221. Inspect changes on container ``id`` 's filesystem
  222. **Example request**:
  223. .. sourcecode:: http
  224. GET /containers/4fa6e0f0c678/changes HTTP/1.1
  225. **Example response**:
  226. .. sourcecode:: http
  227. HTTP/1.1 200 OK
  228. Content-Type: application/json
  229. [
  230. {
  231. "Path":"/dev",
  232. "Kind":0
  233. },
  234. {
  235. "Path":"/dev/kmsg",
  236. "Kind":1
  237. },
  238. {
  239. "Path":"/test",
  240. "Kind":1
  241. }
  242. ]
  243. :statuscode 200: no error
  244. :statuscode 404: no such container
  245. :statuscode 500: server error
  246. Export a container
  247. ******************
  248. .. http:get:: /containers/(id)/export
  249. Export the contents of container ``id``
  250. **Example request**:
  251. .. sourcecode:: http
  252. GET /containers/4fa6e0f0c678/export HTTP/1.1
  253. **Example response**:
  254. .. sourcecode:: http
  255. HTTP/1.1 200 OK
  256. Content-Type: application/octet-stream
  257. {{ STREAM }}
  258. :statuscode 200: no error
  259. :statuscode 404: no such container
  260. :statuscode 500: server error
  261. Start a container
  262. *****************
  263. .. http:post:: /containers/(id)/start
  264. Start the container ``id``
  265. **Example request**:
  266. .. sourcecode:: http
  267. POST /containers/(id)/start HTTP/1.1
  268. Content-Type: application/json
  269. {
  270. "Binds":["/tmp:/tmp"],
  271. "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}]
  272. }
  273. **Example response**:
  274. .. sourcecode:: http
  275. HTTP/1.1 204 No Content
  276. Content-Type: text/plain
  277. :jsonparam hostConfig: the container's host configuration (optional)
  278. :statuscode 204: no error
  279. :statuscode 404: no such container
  280. :statuscode 500: server error
  281. Stop a container
  282. ****************
  283. .. http:post:: /containers/(id)/stop
  284. Stop the container ``id``
  285. **Example request**:
  286. .. sourcecode:: http
  287. POST /containers/e90e34656806/stop?t=5 HTTP/1.1
  288. **Example response**:
  289. .. sourcecode:: http
  290. HTTP/1.1 204 OK
  291. :query t: number of seconds to wait before killing the container
  292. :statuscode 204: no error
  293. :statuscode 404: no such container
  294. :statuscode 500: server error
  295. Restart a container
  296. *******************
  297. .. http:post:: /containers/(id)/restart
  298. Restart the container ``id``
  299. **Example request**:
  300. .. sourcecode:: http
  301. POST /containers/e90e34656806/restart?t=5 HTTP/1.1
  302. **Example response**:
  303. .. sourcecode:: http
  304. HTTP/1.1 204 OK
  305. :query t: number of seconds to wait before killing the container
  306. :statuscode 204: no error
  307. :statuscode 404: no such container
  308. :statuscode 500: server error
  309. Kill a container
  310. ****************
  311. .. http:post:: /containers/(id)/kill
  312. Kill the container ``id``
  313. **Example request**:
  314. .. sourcecode:: http
  315. POST /containers/e90e34656806/kill HTTP/1.1
  316. **Example response**:
  317. .. sourcecode:: http
  318. HTTP/1.1 204 OK
  319. :statuscode 204: no error
  320. :statuscode 404: no such container
  321. :statuscode 500: server error
  322. Attach to a container
  323. *********************
  324. .. http:post:: /containers/(id)/attach
  325. Attach to the container ``id``
  326. **Example request**:
  327. .. sourcecode:: http
  328. POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1
  329. **Example response**:
  330. .. sourcecode:: http
  331. HTTP/1.1 200 OK
  332. Content-Type: application/vnd.docker.raw-stream
  333. {{ STREAM }}
  334. :query logs: 1/True/true or 0/False/false, return logs. Default false
  335. :query stream: 1/True/true or 0/False/false, return stream. Default false
  336. :query stdin: 1/True/true or 0/False/false, if stream=true, attach to stdin. Default false
  337. :query stdout: 1/True/true or 0/False/false, if logs=true, return stdout log, if stream=true, attach to stdout. Default false
  338. :query stderr: 1/True/true or 0/False/false, if logs=true, return stderr log, if stream=true, attach to stderr. Default false
  339. :statuscode 200: no error
  340. :statuscode 400: bad parameter
  341. :statuscode 404: no such container
  342. :statuscode 500: server error
  343. Wait a container
  344. ****************
  345. .. http:post:: /containers/(id)/wait
  346. Block until container ``id`` stops, then returns the exit code
  347. **Example request**:
  348. .. sourcecode:: http
  349. POST /containers/16253994b7c4/wait HTTP/1.1
  350. **Example response**:
  351. .. sourcecode:: http
  352. HTTP/1.1 200 OK
  353. Content-Type: application/json
  354. {"StatusCode":0}
  355. :statuscode 200: no error
  356. :statuscode 404: no such container
  357. :statuscode 500: server error
  358. Remove a container
  359. *******************
  360. .. http:delete:: /containers/(id)
  361. Remove the container ``id`` from the filesystem
  362. **Example request**:
  363. .. sourcecode:: http
  364. DELETE /containers/16253994b7c4?v=1 HTTP/1.1
  365. **Example response**:
  366. .. sourcecode:: http
  367. HTTP/1.1 204 OK
  368. :query v: 1/True/true or 0/False/false, Remove the volumes associated to the container. Default false
  369. :statuscode 204: no error
  370. :statuscode 400: bad parameter
  371. :statuscode 404: no such container
  372. :statuscode 500: server error
  373. Copy files or folders from a container
  374. **************************************
  375. .. http:post:: /containers/(id)/copy
  376. Copy files or folders of container ``id``
  377. **Example request**:
  378. .. sourcecode:: http
  379. POST /containers/4fa6e0f0c678/copy HTTP/1.1
  380. Content-Type: application/json
  381. {
  382. "Resource":"test.txt"
  383. }
  384. **Example response**:
  385. .. sourcecode:: http
  386. HTTP/1.1 200 OK
  387. Content-Type: application/octet-stream
  388. {{ STREAM }}
  389. :statuscode 200: no error
  390. :statuscode 404: no such container
  391. :statuscode 500: server error
  392. 2.2 Images
  393. ----------
  394. List Images
  395. ***********
  396. .. http:get:: /images/(format)
  397. List images ``format`` could be json or viz (json default)
  398. **Example request**:
  399. .. sourcecode:: http
  400. GET /images/json?all=0 HTTP/1.1
  401. **Example response**:
  402. .. sourcecode:: http
  403. HTTP/1.1 200 OK
  404. Content-Type: application/json
  405. [
  406. {
  407. "Repository":"ubuntu",
  408. "Tag":"precise",
  409. "Id":"b750fe79269d",
  410. "Created":1364102658,
  411. "Size":24653,
  412. "VirtualSize":180116135
  413. },
  414. {
  415. "Repository":"ubuntu",
  416. "Tag":"12.04",
  417. "Id":"b750fe79269d",
  418. "Created":1364102658,
  419. "Size":24653,
  420. "VirtualSize":180116135
  421. }
  422. ]
  423. **Example request**:
  424. .. sourcecode:: http
  425. GET /images/viz HTTP/1.1
  426. **Example response**:
  427. .. sourcecode:: http
  428. HTTP/1.1 200 OK
  429. Content-Type: text/plain
  430. digraph docker {
  431. "d82cbacda43a" -> "074be284591f"
  432. "1496068ca813" -> "08306dc45919"
  433. "08306dc45919" -> "0e7893146ac2"
  434. "b750fe79269d" -> "1496068ca813"
  435. base -> "27cf78414709" [style=invis]
  436. "f71189fff3de" -> "9a33b36209ed"
  437. "27cf78414709" -> "b750fe79269d"
  438. "0e7893146ac2" -> "d6434d954665"
  439. "d6434d954665" -> "d82cbacda43a"
  440. base -> "e9aa60c60128" [style=invis]
  441. "074be284591f" -> "f71189fff3de"
  442. "b750fe79269d" [label="b750fe79269d\nubuntu",shape=box,fillcolor="paleturquoise",style="filled,rounded"];
  443. "e9aa60c60128" [label="e9aa60c60128\ncentos",shape=box,fillcolor="paleturquoise",style="filled,rounded"];
  444. "9a33b36209ed" [label="9a33b36209ed\nfedora",shape=box,fillcolor="paleturquoise",style="filled,rounded"];
  445. base [style=invisible]
  446. }
  447. :query all: 1/True/true or 0/False/false, Show all containers. Only running containers are shown by default
  448. :statuscode 200: no error
  449. :statuscode 400: bad parameter
  450. :statuscode 500: server error
  451. Create an image
  452. ***************
  453. .. http:post:: /images/create
  454. Create an image, either by pull it from the registry or by importing it
  455. **Example request**:
  456. .. sourcecode:: http
  457. POST /images/create?fromImage=ubuntu HTTP/1.1
  458. **Example response**:
  459. .. sourcecode:: http
  460. HTTP/1.1 200 OK
  461. Content-Type: application/json
  462. {"status":"Pulling..."}
  463. {"status":"Pulling", "progress":"1/? (n/a)"}
  464. {"error":"Invalid..."}
  465. ...
  466. :query fromImage: name of the image to pull
  467. :query fromSrc: source to import, - means stdin
  468. :query repo: repository
  469. :query tag: tag
  470. :query registry: the registry to pull from
  471. :statuscode 200: no error
  472. :statuscode 500: server error
  473. Insert a file in an image
  474. *************************
  475. .. http:post:: /images/(name)/insert
  476. Insert a file from ``url`` in the image ``name`` at ``path``
  477. **Example request**:
  478. .. sourcecode:: http
  479. POST /images/test/insert?path=/usr&url=myurl HTTP/1.1
  480. **Example response**:
  481. .. sourcecode:: http
  482. HTTP/1.1 200 OK
  483. Content-Type: application/json
  484. {"status":"Inserting..."}
  485. {"status":"Inserting", "progress":"1/? (n/a)"}
  486. {"error":"Invalid..."}
  487. ...
  488. :statuscode 200: no error
  489. :statuscode 500: server error
  490. Inspect an image
  491. ****************
  492. .. http:get:: /images/(name)/json
  493. Return low-level information on the image ``name``
  494. **Example request**:
  495. .. sourcecode:: http
  496. GET /images/centos/json HTTP/1.1
  497. **Example response**:
  498. .. sourcecode:: http
  499. HTTP/1.1 200 OK
  500. Content-Type: application/json
  501. {
  502. "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
  503. "parent":"27cf784147099545",
  504. "created":"2013-03-23T22:24:18.818426-07:00",
  505. "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0",
  506. "container_config":
  507. {
  508. "Hostname":"",
  509. "User":"",
  510. "Memory":0,
  511. "MemorySwap":0,
  512. "AttachStdin":false,
  513. "AttachStdout":false,
  514. "AttachStderr":false,
  515. "PortSpecs":null,
  516. "Tty":true,
  517. "OpenStdin":true,
  518. "StdinOnce":false,
  519. "Env":null,
  520. "Cmd": ["/bin/bash"]
  521. ,"Dns":null,
  522. "Image":"centos",
  523. "Volumes":null,
  524. "VolumesFrom":"",
  525. "WorkingDir":""
  526. },
  527. "Size": 6824592
  528. }
  529. :statuscode 200: no error
  530. :statuscode 404: no such image
  531. :statuscode 409: conflict between containers and images
  532. :statuscode 500: server error
  533. Get the history of an image
  534. ***************************
  535. .. http:get:: /images/(name)/history
  536. Return the history of the image ``name``
  537. **Example request**:
  538. .. sourcecode:: http
  539. GET /images/fedora/history HTTP/1.1
  540. **Example response**:
  541. .. sourcecode:: http
  542. HTTP/1.1 200 OK
  543. Content-Type: application/json
  544. [
  545. {
  546. "Id":"b750fe79269d",
  547. "Created":1364102658,
  548. "CreatedBy":"/bin/bash"
  549. },
  550. {
  551. "Id":"27cf78414709",
  552. "Created":1364068391,
  553. "CreatedBy":""
  554. }
  555. ]
  556. :statuscode 200: no error
  557. :statuscode 404: no such image
  558. :statuscode 500: server error
  559. Push an image on the registry
  560. *****************************
  561. .. http:post:: /images/(name)/push
  562. Push the image ``name`` on the registry
  563. **Example request**:
  564. .. sourcecode:: http
  565. POST /images/test/push HTTP/1.1
  566. {{ authConfig }}
  567. **Example response**:
  568. .. sourcecode:: http
  569. HTTP/1.1 200 OK
  570. Content-Type: application/json
  571. {"status":"Pushing..."}
  572. {"status":"Pushing", "progress":"1/? (n/a)"}
  573. {"error":"Invalid..."}
  574. ...
  575. :query registry: the registry you wan to push, optional
  576. :statuscode 200: no error
  577. :statuscode 404: no such image
  578. :statuscode 500: server error
  579. Tag an image into a repository
  580. ******************************
  581. .. http:post:: /images/(name)/tag
  582. Tag the image ``name`` into a repository
  583. **Example request**:
  584. .. sourcecode:: http
  585. POST /images/test/tag?repo=myrepo&force=0 HTTP/1.1
  586. **Example response**:
  587. .. sourcecode:: http
  588. HTTP/1.1 200 OK
  589. :query repo: The repository to tag in
  590. :query force: 1/True/true or 0/False/false, default false
  591. :statuscode 200: no error
  592. :statuscode 400: bad parameter
  593. :statuscode 404: no such image
  594. :statuscode 409: conflict
  595. :statuscode 500: server error
  596. Remove an image
  597. ***************
  598. .. http:delete:: /images/(name)
  599. Remove the image ``name`` from the filesystem
  600. **Example request**:
  601. .. sourcecode:: http
  602. DELETE /images/test HTTP/1.1
  603. **Example response**:
  604. .. sourcecode:: http
  605. HTTP/1.1 200 OK
  606. Content-type: application/json
  607. [
  608. {"Untagged":"3e2f21a89f"},
  609. {"Deleted":"3e2f21a89f"},
  610. {"Deleted":"53b4f83ac9"}
  611. ]
  612. :statuscode 200: no error
  613. :statuscode 404: no such image
  614. :statuscode 409: conflict
  615. :statuscode 500: server error
  616. Search images
  617. *************
  618. .. http:get:: /images/search
  619. Search for an image in the docker index
  620. **Example request**:
  621. .. sourcecode:: http
  622. GET /images/search?term=sshd HTTP/1.1
  623. **Example response**:
  624. .. sourcecode:: http
  625. HTTP/1.1 200 OK
  626. Content-Type: application/json
  627. [
  628. {
  629. "Name":"cespare/sshd",
  630. "Description":""
  631. },
  632. {
  633. "Name":"johnfuller/sshd",
  634. "Description":""
  635. },
  636. {
  637. "Name":"dhrp/mongodb-sshd",
  638. "Description":""
  639. }
  640. ]
  641. :query term: term to search
  642. :statuscode 200: no error
  643. :statuscode 500: server error
  644. 2.3 Misc
  645. --------
  646. Build an image from Dockerfile via stdin
  647. ****************************************
  648. .. http:post:: /build
  649. Build an image from Dockerfile via stdin
  650. **Example request**:
  651. .. sourcecode:: http
  652. POST /build HTTP/1.1
  653. {{ STREAM }}
  654. **Example response**:
  655. .. sourcecode:: http
  656. HTTP/1.1 200 OK
  657. {{ STREAM }}
  658. The stream must be a tar archive compressed with one of the following algorithms:
  659. identity (no compression), gzip, bzip2, xz. The archive must include a file called
  660. `Dockerfile` at its root. It may include any number of other files, which will be
  661. accessible in the build context (See the ADD build command).
  662. The Content-type header should be set to "application/tar".
  663. :query t: repository name (and optionally a tag) to be applied to the resulting image in case of success
  664. :query q: suppress verbose build output
  665. :query nocache: do not use the cache when building the image
  666. :statuscode 200: no error
  667. :statuscode 500: server error
  668. Check auth configuration
  669. ************************
  670. .. http:post:: /auth
  671. Get the default username and email
  672. **Example request**:
  673. .. sourcecode:: http
  674. POST /auth HTTP/1.1
  675. Content-Type: application/json
  676. {
  677. "username":"hannibal",
  678. "password:"xxxx",
  679. "email":"hannibal@a-team.com",
  680. "serveraddress":"https://index.docker.io/v1/"
  681. }
  682. **Example response**:
  683. .. sourcecode:: http
  684. HTTP/1.1 200 OK
  685. :statuscode 200: no error
  686. :statuscode 204: no error
  687. :statuscode 500: server error
  688. Display system-wide information
  689. *******************************
  690. .. http:get:: /info
  691. Display system-wide information
  692. **Example request**:
  693. .. sourcecode:: http
  694. GET /info HTTP/1.1
  695. **Example response**:
  696. .. sourcecode:: http
  697. HTTP/1.1 200 OK
  698. Content-Type: application/json
  699. {
  700. "Containers":11,
  701. "Images":16,
  702. "Debug":false,
  703. "NFd": 11,
  704. "NGoroutines":21,
  705. "MemoryLimit":true,
  706. "SwapLimit":false,
  707. "IPv4Forwarding":true
  708. }
  709. :statuscode 200: no error
  710. :statuscode 500: server error
  711. Show the docker version information
  712. ***********************************
  713. .. http:get:: /version
  714. Show the docker version information
  715. **Example request**:
  716. .. sourcecode:: http
  717. GET /version HTTP/1.1
  718. **Example response**:
  719. .. sourcecode:: http
  720. HTTP/1.1 200 OK
  721. Content-Type: application/json
  722. {
  723. "Version":"0.2.2",
  724. "GitCommit":"5a2a5cc+CHANGES",
  725. "GoVersion":"go1.0.3"
  726. }
  727. :statuscode 200: no error
  728. :statuscode 500: server error
  729. Create a new image from a container's changes
  730. *********************************************
  731. .. http:post:: /commit
  732. Create a new image from a container's changes
  733. **Example request**:
  734. .. sourcecode:: http
  735. POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1
  736. Content-Type: application/json
  737. {
  738. "Cmd": ["cat", "/world"],
  739. "PortSpecs":["22"]
  740. }
  741. **Example response**:
  742. .. sourcecode:: http
  743. HTTP/1.1 201 OK
  744. Content-Type: application/vnd.docker.raw-stream
  745. {"Id":"596069db4bf5"}
  746. :query container: source container
  747. :query repo: repository
  748. :query tag: tag
  749. :query m: commit message
  750. :query author: author (eg. "John Hannibal Smith <hannibal@a-team.com>")
  751. :statuscode 201: no error
  752. :statuscode 404: no such container
  753. :statuscode 500: server error
  754. Monitor Docker's events
  755. ***********************
  756. .. http:get:: /events
  757. Get events from docker, either in real time via streaming, or via polling (using `since`)
  758. **Example request**:
  759. .. sourcecode:: http
  760. GET /events?since=1374067924
  761. **Example response**:
  762. .. sourcecode:: http
  763. HTTP/1.1 200 OK
  764. Content-Type: application/json
  765. {"status":"create","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067924}
  766. {"status":"start","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067924}
  767. {"status":"stop","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067966}
  768. {"status":"destroy","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067970}
  769. :query since: timestamp used for polling
  770. :statuscode 200: no error
  771. :statuscode 500: server error
  772. 3. Going further
  773. ================
  774. 3.1 Inside 'docker run'
  775. -----------------------
  776. Here are the steps of 'docker run' :
  777. * Create the container
  778. * If the status code is 404, it means the image doesn't exists:
  779. * Try to pull it
  780. * Then retry to create the container
  781. * Start the container
  782. * If you are not in detached mode:
  783. * Attach to the container, using logs=1 (to have stdout and stderr from the container's start) and stream=1
  784. * If in detached mode or only stdin is attached:
  785. * Display the container's id
  786. 3.2 Hijacking
  787. -------------
  788. In this version of the API, /attach, uses hijacking to transport stdin, stdout and stderr on the same socket. This might change in the future.
  789. 3.3 CORS Requests
  790. -----------------
  791. To enable cross origin requests to the remote api add the flag "-api-enable-cors" when running docker in daemon mode.
  792. .. code-block:: bash
  793. docker -d -H="192.168.1.9:4243" -api-enable-cors