{"__v":39,"_id":"543033237d487022005b4034","api":{"auth":"never","basic_auth":false,"params":[],"results":{"codes":[]},"settings":"","try":true,"url":""},"body":"Ghost is built on top of a RESTful JSON API. This API is used for all data access inside of the Ghost software itself, meaning the API is the heart of the software, not an afterthought or additional layer.\n\nThe API is built on the principles of REST. The URLs are resource-oriented, so that they are easily guessable, and follow a pattern. The API makes use of many HTTP features such as the verbs and response codes, and HTTP authorization is used for private access. Many other design decisions were based on the [JSONAPI](http://jsonapi.org/format) spec, although our API does not follow the JSONAPI spec 100% at present.\n\n## Stability and progress\n\nThe API is still under very (very) heavy development and subject to regular breaking changes. For this reason, we have kept access to the API somewhat restricted, but are now working on rolling out access via OAuth client & user authentication. \n\nAs of Ghost 0.7.2, if you enable the Beta 'Public API' feature, you will be able to make use of the Public API from within a Ghost theme. It is possible to extend this to other domains, but at present this requires DB manipulation, see [Client Authentication](doc:client-authentication) for further details.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Access Levels\"\n}\n[/block]\nThe Ghost API is split into what is considered 'Public' and 'Private' requests, and for the time being, only the Public API is 'officially' available via [Client Authentication](doc:client-authentication). You can find out more about the difference between the Public and Private API below, as well as detail on how to make use of them.\n\n## Public API\n\nThe 'Public' API essentially reflects the behaviour of a blog - it provides read access to any data that a user/reader of a blog would be able to see.\n\nThis means published posts, active users and all tags. In the near future, this will be extended to include certain 'public' settings, known within Ghost as the `blog` settings, such as the title and description - all of which would also be accessible to a visitor to a blog.\n\nAccess to the Public API is provided in one of two ways at present:\n\n- Data can be read via 'GET' requests to the `posts`, `users` and `tags` endpoints, and from the [get helper](http://themes.ghost.org/docs/get) in a Ghost theme. The get helper operates server side and handles authentication for you.\n\n- Browser-based clients (e.g. client-side JavaScript scripts or apps) can make ajax calls using [Client Authentication](doc:client-authentication). This means a browser based client (a 'public client') is allowed to read these endpoints by providing a `client_id` and `client_secret`, providing the request comes from a known, trusted domain.\n\nFor the time being Client Authentication is restricted to the domain specified in your `config.js` file, meaning that requests that come from a theme will work, but requests from another site will not. This can be overridden via the DB. For Ghost themes, all of the complexity of finding and providing the client credentials is managed via a JavaScript function called [`ghost.url.api()`](http://themes.ghost.org/docs/ghost-url-api).\n\nFor more information on how this works please see the [Client Authentication](doc:client-authentication) section, or the [ghost.url.api()](http://themes.ghost.org/docs/ghost-url-api) docs in themes.\n\n## Private API\n\nThe 'Private' API provides access to blog data in accordance with the permissions of the user making the request. This includes all write access, and read access for any private data, for example draft posts and inactive users.\n\nWe're working on adding more standard OAuth flows for getting private access to the API. In the meantime, the only OAuth flow available is to use a standard user login to get a Bearer Token. Therefore, getting access to write data from 3rd party apps is not impossible, but is not ideal. \n\nYou can read about how this works in the [User Authentication](doc:user-authentication) section.","category":"543033237d487022005b4033","createdAt":"2014-10-04T16:44:29.615Z","excerpt":"Get started querying the Ghost API.","githubsync":"","hidden":false,"is_link":false,"link_external":false,"link_url":"","order":0,"project":"543023ed7d487022005b3ff8","slug":"getting-started","sync_unique":"","title":"Overview","type":"basic","updates":[],"user":"542c5cfcddd3190e00228849","version":"543033227d487022005b4032","childrenPages":[]}

Overview

Get started querying the Ghost API.

Ghost is built on top of a RESTful JSON API. This API is used for all data access inside of the Ghost software itself, meaning the API is the heart of the software, not an afterthought or additional layer. The API is built on the principles of REST. The URLs are resource-oriented, so that they are easily guessable, and follow a pattern. The API makes use of many HTTP features such as the verbs and response codes, and HTTP authorization is used for private access. Many other design decisions were based on the [JSONAPI](http://jsonapi.org/format) spec, although our API does not follow the JSONAPI spec 100% at present. ## Stability and progress The API is still under very (very) heavy development and subject to regular breaking changes. For this reason, we have kept access to the API somewhat restricted, but are now working on rolling out access via OAuth client & user authentication. As of Ghost 0.7.2, if you enable the Beta 'Public API' feature, you will be able to make use of the Public API from within a Ghost theme. It is possible to extend this to other domains, but at present this requires DB manipulation, see [Client Authentication](doc:client-authentication) for further details. [block:api-header] { "type": "basic", "title": "Access Levels" } [/block] The Ghost API is split into what is considered 'Public' and 'Private' requests, and for the time being, only the Public API is 'officially' available via [Client Authentication](doc:client-authentication). You can find out more about the difference between the Public and Private API below, as well as detail on how to make use of them. ## Public API The 'Public' API essentially reflects the behaviour of a blog - it provides read access to any data that a user/reader of a blog would be able to see. This means published posts, active users and all tags. In the near future, this will be extended to include certain 'public' settings, known within Ghost as the `blog` settings, such as the title and description - all of which would also be accessible to a visitor to a blog. Access to the Public API is provided in one of two ways at present: - Data can be read via 'GET' requests to the `posts`, `users` and `tags` endpoints, and from the [get helper](http://themes.ghost.org/docs/get) in a Ghost theme. The get helper operates server side and handles authentication for you. - Browser-based clients (e.g. client-side JavaScript scripts or apps) can make ajax calls using [Client Authentication](doc:client-authentication). This means a browser based client (a 'public client') is allowed to read these endpoints by providing a `client_id` and `client_secret`, providing the request comes from a known, trusted domain. For the time being Client Authentication is restricted to the domain specified in your `config.js` file, meaning that requests that come from a theme will work, but requests from another site will not. This can be overridden via the DB. For Ghost themes, all of the complexity of finding and providing the client credentials is managed via a JavaScript function called [`ghost.url.api()`](http://themes.ghost.org/docs/ghost-url-api). For more information on how this works please see the [Client Authentication](doc:client-authentication) section, or the [ghost.url.api()](http://themes.ghost.org/docs/ghost-url-api) docs in themes. ## Private API The 'Private' API provides access to blog data in accordance with the permissions of the user making the request. This includes all write access, and read access for any private data, for example draft posts and inactive users. We're working on adding more standard OAuth flows for getting private access to the API. In the meantime, the only OAuth flow available is to use a standard user login to get a Bearer Token. Therefore, getting access to write data from 3rd party apps is not impossible, but is not ideal. You can read about how this works in the [User Authentication](doc:user-authentication) section.
Ghost is built on top of a RESTful JSON API. This API is used for all data access inside of the Ghost software itself, meaning the API is the heart of the software, not an afterthought or additional layer. The API is built on the principles of REST. The URLs are resource-oriented, so that they are easily guessable, and follow a pattern. The API makes use of many HTTP features such as the verbs and response codes, and HTTP authorization is used for private access. Many other design decisions were based on the [JSONAPI](http://jsonapi.org/format) spec, although our API does not follow the JSONAPI spec 100% at present. ## Stability and progress The API is still under very (very) heavy development and subject to regular breaking changes. For this reason, we have kept access to the API somewhat restricted, but are now working on rolling out access via OAuth client & user authentication. As of Ghost 0.7.2, if you enable the Beta 'Public API' feature, you will be able to make use of the Public API from within a Ghost theme. It is possible to extend this to other domains, but at present this requires DB manipulation, see [Client Authentication](doc:client-authentication) for further details. [block:api-header] { "type": "basic", "title": "Access Levels" } [/block] The Ghost API is split into what is considered 'Public' and 'Private' requests, and for the time being, only the Public API is 'officially' available via [Client Authentication](doc:client-authentication). You can find out more about the difference between the Public and Private API below, as well as detail on how to make use of them. ## Public API The 'Public' API essentially reflects the behaviour of a blog - it provides read access to any data that a user/reader of a blog would be able to see. This means published posts, active users and all tags. In the near future, this will be extended to include certain 'public' settings, known within Ghost as the `blog` settings, such as the title and description - all of which would also be accessible to a visitor to a blog. Access to the Public API is provided in one of two ways at present: - Data can be read via 'GET' requests to the `posts`, `users` and `tags` endpoints, and from the [get helper](http://themes.ghost.org/docs/get) in a Ghost theme. The get helper operates server side and handles authentication for you. - Browser-based clients (e.g. client-side JavaScript scripts or apps) can make ajax calls using [Client Authentication](doc:client-authentication). This means a browser based client (a 'public client') is allowed to read these endpoints by providing a `client_id` and `client_secret`, providing the request comes from a known, trusted domain. For the time being Client Authentication is restricted to the domain specified in your `config.js` file, meaning that requests that come from a theme will work, but requests from another site will not. This can be overridden via the DB. For Ghost themes, all of the complexity of finding and providing the client credentials is managed via a JavaScript function called [`ghost.url.api()`](http://themes.ghost.org/docs/ghost-url-api). For more information on how this works please see the [Client Authentication](doc:client-authentication) section, or the [ghost.url.api()](http://themes.ghost.org/docs/ghost-url-api) docs in themes. ## Private API The 'Private' API provides access to blog data in accordance with the permissions of the user making the request. This includes all write access, and read access for any private data, for example draft posts and inactive users. We're working on adding more standard OAuth flows for getting private access to the API. In the meantime, the only OAuth flow available is to use a standard user login to get a Bearer Token. Therefore, getting access to write data from 3rd party apps is not impossible, but is not ideal. You can read about how this works in the [User Authentication](doc:user-authentication) section.
{"__v":16,"_id":"55a92c88cf45e1390093f31d","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"Ghost uses HTTP response codes to indicate the success or failure of an API request.\n\nThe codes consist of 3 numbers. The first number generally denotes the type of error.\n\n2xx codes generally indicate success,  4xx codes indicate a problem with the request that was sent, such as failed authentication or incorrect query parameter/syntax etc, and 5xx codes means that something went wrong on the blog's server.\n\n## Error responses\n\nErrors are returned in JSON, with a top-level `errors` key containing an array of errors that have been generated (validations can trigger multiple errors).\n\nEach error currently has a `message` and an `errorType`.\n\nThis error response format is likely to get an overhaul in the near future.\n\n\n### Examples\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"errors\\\": [\\n    {\\n      \\\"message\\\": \\\"Access denied.\\\",\\n      \\\"errorType\\\": \\\"UnauthorizedError\\\"\\n    }\\n  ]\\n} \",\n      \"language\": \"json\",\n      \"name\": \"401 Unauthorised\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"errors\\\": [\\n    {\\n      \\\"message\\\": \\\"Validation (matches) failed for limit\\\",\\n      \\\"errorType\\\": \\\"ValidationError\\\"\\n    }\\n  ]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"422 Unprocessable Entity\"\n    }\n  ]\n}\n[/block]\n## HTTP success/error codes used:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"\",\n    \"h-1\": \"\",\n    \"0-0\": \"200\",\n    \"0-1\": \"Success, request performed as expected.\",\n    \"2-0\": \"400\",\n    \"2-1\": \"Bad request\",\n    \"3-0\": \"401\",\n    \"3-1\": \"Unauthorized\",\n    \"5-0\": \"404\",\n    \"5-1\": \"Not found\",\n    \"4-0\": \"403\",\n    \"4-1\": \"No permission\",\n    \"6-0\": \"405\",\n    \"6-1\": \"Method not allowed\",\n    \"7-0\": \"413\",\n    \"7-1\": \"Requested entity too large\",\n    \"8-0\": \"415\",\n    \"8-1\": \"Unsupported media\",\n    \"9-0\": \"422\",\n    \"9-1\": \"Validation error\",\n    \"10-0\": \"429\",\n    \"10-1\": \"Too many requests\",\n    \"11-0\": \"500\",\n    \"11-1\": \"Internal server error, Email error\",\n    \"1-0\": \"201\",\n    \"1-1\": \"Created, object created\"\n  },\n  \"cols\": 2,\n  \"rows\": 12\n}\n[/block]","category":"55a92c6d27a17d2100525282","createdAt":"2015-07-17T16:25:44.964Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"543023ed7d487022005b3ff8","slug":"errors","sync_unique":"","title":"Errors","type":"basic","updates":[],"user":"542c5cfcddd3190e00228849","version":"543033227d487022005b4032","childrenPages":[]}

Errors


Ghost uses HTTP response codes to indicate the success or failure of an API request. The codes consist of 3 numbers. The first number generally denotes the type of error. 2xx codes generally indicate success, 4xx codes indicate a problem with the request that was sent, such as failed authentication or incorrect query parameter/syntax etc, and 5xx codes means that something went wrong on the blog's server. ## Error responses Errors are returned in JSON, with a top-level `errors` key containing an array of errors that have been generated (validations can trigger multiple errors). Each error currently has a `message` and an `errorType`. This error response format is likely to get an overhaul in the near future. ### Examples [block:code] { "codes": [ { "code": "{\n \"errors\": [\n {\n \"message\": \"Access denied.\",\n \"errorType\": \"UnauthorizedError\"\n }\n ]\n} ", "language": "json", "name": "401 Unauthorised" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"errors\": [\n {\n \"message\": \"Validation (matches) failed for limit\",\n \"errorType\": \"ValidationError\"\n }\n ]\n}", "language": "json", "name": "422 Unprocessable Entity" } ] } [/block] ## HTTP success/error codes used: [block:parameters] { "data": { "h-0": "", "h-1": "", "0-0": "200", "0-1": "Success, request performed as expected.", "2-0": "400", "2-1": "Bad request", "3-0": "401", "3-1": "Unauthorized", "5-0": "404", "5-1": "Not found", "4-0": "403", "4-1": "No permission", "6-0": "405", "6-1": "Method not allowed", "7-0": "413", "7-1": "Requested entity too large", "8-0": "415", "8-1": "Unsupported media", "9-0": "422", "9-1": "Validation error", "10-0": "429", "10-1": "Too many requests", "11-0": "500", "11-1": "Internal server error, Email error", "1-0": "201", "1-1": "Created, object created" }, "cols": 2, "rows": 12 } [/block]
Ghost uses HTTP response codes to indicate the success or failure of an API request. The codes consist of 3 numbers. The first number generally denotes the type of error. 2xx codes generally indicate success, 4xx codes indicate a problem with the request that was sent, such as failed authentication or incorrect query parameter/syntax etc, and 5xx codes means that something went wrong on the blog's server. ## Error responses Errors are returned in JSON, with a top-level `errors` key containing an array of errors that have been generated (validations can trigger multiple errors). Each error currently has a `message` and an `errorType`. This error response format is likely to get an overhaul in the near future. ### Examples [block:code] { "codes": [ { "code": "{\n \"errors\": [\n {\n \"message\": \"Access denied.\",\n \"errorType\": \"UnauthorizedError\"\n }\n ]\n} ", "language": "json", "name": "401 Unauthorised" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"errors\": [\n {\n \"message\": \"Validation (matches) failed for limit\",\n \"errorType\": \"ValidationError\"\n }\n ]\n}", "language": "json", "name": "422 Unprocessable Entity" } ] } [/block] ## HTTP success/error codes used: [block:parameters] { "data": { "h-0": "", "h-1": "", "0-0": "200", "0-1": "Success, request performed as expected.", "2-0": "400", "2-1": "Bad request", "3-0": "401", "3-1": "Unauthorized", "5-0": "404", "5-1": "Not found", "4-0": "403", "4-1": "No permission", "6-0": "405", "6-1": "Method not allowed", "7-0": "413", "7-1": "Requested entity too large", "8-0": "415", "8-1": "Unsupported media", "9-0": "422", "9-1": "Validation error", "10-0": "429", "10-1": "Too many requests", "11-0": "500", "11-1": "Internal server error, Email error", "1-0": "201", "1-1": "Created, object created" }, "cols": 2, "rows": 12 } [/block]
{"__v":4,"_id":"55a92c80cf45e1390093f31b","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"When fetching multiple resources from an endpoint, e.g. performing a 'browse' request the number of items returned will be limited to 15 by default.\n\nGhost's API currently uses page-based pagination, which is controlled via the two parameters [Limit](doc:limit) and [Page](doc:page). The API returns **page** 1 by default, and requesting **page** 2 will send the next 15 items. Alternatively you can make a request for more or less items, so that you can get the exact data that you need, by changing the **limit**.\n\n\n\n\nWhen browsing the **posts**, **users** and **tags** endpoints you will retrieve an array of your queried resource and a meta object that includes a pagination object. \n\nThis provides you with the following attributes:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"page - the current page number\\nprev - the previous page number\\nnext - the next page number\\npages - the number of pages available\\ntotal - the number of posts available\\nlimit - the number of posts per page\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]","category":"55a92c6d27a17d2100525282","createdAt":"2015-07-17T16:25:36.744Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"543023ed7d487022005b3ff8","slug":"pagination","sync_unique":"","title":"Pagination","type":"basic","updates":[],"user":"542c5cfcddd3190e00228849","version":"543033227d487022005b4032","childrenPages":[]}

Pagination


When fetching multiple resources from an endpoint, e.g. performing a 'browse' request the number of items returned will be limited to 15 by default. Ghost's API currently uses page-based pagination, which is controlled via the two parameters [Limit](doc:limit) and [Page](doc:page). The API returns **page** 1 by default, and requesting **page** 2 will send the next 15 items. Alternatively you can make a request for more or less items, so that you can get the exact data that you need, by changing the **limit**. When browsing the **posts**, **users** and **tags** endpoints you will retrieve an array of your queried resource and a meta object that includes a pagination object. This provides you with the following attributes: [block:code] { "codes": [ { "code": "page - the current page number\nprev - the previous page number\nnext - the next page number\npages - the number of pages available\ntotal - the number of posts available\nlimit - the number of posts per page", "language": "text" } ] } [/block]
When fetching multiple resources from an endpoint, e.g. performing a 'browse' request the number of items returned will be limited to 15 by default. Ghost's API currently uses page-based pagination, which is controlled via the two parameters [Limit](doc:limit) and [Page](doc:page). The API returns **page** 1 by default, and requesting **page** 2 will send the next 15 items. Alternatively you can make a request for more or less items, so that you can get the exact data that you need, by changing the **limit**. When browsing the **posts**, **users** and **tags** endpoints you will retrieve an array of your queried resource and a meta object that includes a pagination object. This provides you with the following attributes: [block:code] { "codes": [ { "code": "page - the current page number\nprev - the previous page number\nnext - the next page number\npages - the number of pages available\ntotal - the number of posts available\nlimit - the number of posts per page", "language": "text" } ] } [/block]
{"__v":49,"_id":"5641f07b38e37e0d0049fe96","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"You can make your API queries more selective using a range of parameters. \n\nThese parameters will select what is included in your collection and how it is structured.\n\nThe [`/users/`](doc:users), [`/posts/`](doc:posts) and [`/tags/`](doc:tags) endpoints are by default **Browse** requests. These can be changed to a **Read** request  if certain resource fields are specified in the request. E.g for the [`/posts/`](doc:posts) you can specify the *slug*.\n\n> Note: For **Read** requests, only the [**include**](doc:include) parameter is valid.\n\nYou can see which parameters apply by viewing the documentation for each particular endpoint.\n\nHere is a full list of the parameters you can use with links to more detailed documentation:\n* [**limit**](doc:limit) - selects the number of results for each page of a collection.\n* [**page**](doc:page) - selects which page of collection to return.\n* [**order**](doc:order) - choose how to order your collection.\n* [**include**](doc:include) - choose which related objects to add to your collection.\n* [**fields**](doc:fields) - reduce collection to only selected fields.\n* [**filter**](doc:filter) - creates more complicated, logic based queries using GQL.\n\n## Additional Information\n\n### **Browse** request\nReturns a paginated collection.\n\n* [`/users/`](doc:users), [`/posts/`](doc:posts) and [`/tags/`](doc:tags) endpoints are by default **Browse** requests.\n* Specify certain resource fields, changes the request to a *Read* request\n\n\n### **Read** request\nReturns a single object.\n\n*  [`/posts/:id`](doc:postsid), [`/posts/slug/:slug`](doc:postsslugslug), [`/tags/:id`](doc:tagsid), [`/tags/slug/:slug`](doc:tagsslugslug), [`/users/:id`](doc:usersid), [`/users/slug/:slug`](doc:usersslug) and  [`/users/email/:email`](doc:usersemailemail) are **Read** requests.\n* Can only use the [**include**](doc:include) parameter.","category":"55a92c6d27a17d2100525282","createdAt":"2015-11-10T13:26:19.816Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"543023ed7d487022005b3ff8","slug":"parameters","sync_unique":"","title":"Parameters","type":"basic","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

Parameters


You can make your API queries more selective using a range of parameters. These parameters will select what is included in your collection and how it is structured. The [`/users/`](doc:users), [`/posts/`](doc:posts) and [`/tags/`](doc:tags) endpoints are by default **Browse** requests. These can be changed to a **Read** request if certain resource fields are specified in the request. E.g for the [`/posts/`](doc:posts) you can specify the *slug*. > Note: For **Read** requests, only the [**include**](doc:include) parameter is valid. You can see which parameters apply by viewing the documentation for each particular endpoint. Here is a full list of the parameters you can use with links to more detailed documentation: * [**limit**](doc:limit) - selects the number of results for each page of a collection. * [**page**](doc:page) - selects which page of collection to return. * [**order**](doc:order) - choose how to order your collection. * [**include**](doc:include) - choose which related objects to add to your collection. * [**fields**](doc:fields) - reduce collection to only selected fields. * [**filter**](doc:filter) - creates more complicated, logic based queries using GQL. ## Additional Information ### **Browse** request Returns a paginated collection. * [`/users/`](doc:users), [`/posts/`](doc:posts) and [`/tags/`](doc:tags) endpoints are by default **Browse** requests. * Specify certain resource fields, changes the request to a *Read* request ### **Read** request Returns a single object. * [`/posts/:id`](doc:postsid), [`/posts/slug/:slug`](doc:postsslugslug), [`/tags/:id`](doc:tagsid), [`/tags/slug/:slug`](doc:tagsslugslug), [`/users/:id`](doc:usersid), [`/users/slug/:slug`](doc:usersslug) and [`/users/email/:email`](doc:usersemailemail) are **Read** requests. * Can only use the [**include**](doc:include) parameter.
You can make your API queries more selective using a range of parameters. These parameters will select what is included in your collection and how it is structured. The [`/users/`](doc:users), [`/posts/`](doc:posts) and [`/tags/`](doc:tags) endpoints are by default **Browse** requests. These can be changed to a **Read** request if certain resource fields are specified in the request. E.g for the [`/posts/`](doc:posts) you can specify the *slug*. > Note: For **Read** requests, only the [**include**](doc:include) parameter is valid. You can see which parameters apply by viewing the documentation for each particular endpoint. Here is a full list of the parameters you can use with links to more detailed documentation: * [**limit**](doc:limit) - selects the number of results for each page of a collection. * [**page**](doc:page) - selects which page of collection to return. * [**order**](doc:order) - choose how to order your collection. * [**include**](doc:include) - choose which related objects to add to your collection. * [**fields**](doc:fields) - reduce collection to only selected fields. * [**filter**](doc:filter) - creates more complicated, logic based queries using GQL. ## Additional Information ### **Browse** request Returns a paginated collection. * [`/users/`](doc:users), [`/posts/`](doc:posts) and [`/tags/`](doc:tags) endpoints are by default **Browse** requests. * Specify certain resource fields, changes the request to a *Read* request ### **Read** request Returns a single object. * [`/posts/:id`](doc:postsid), [`/posts/slug/:slug`](doc:postsslugslug), [`/tags/:id`](doc:tagsid), [`/tags/slug/:slug`](doc:tagsslugslug), [`/users/:id`](doc:usersid), [`/users/slug/:slug`](doc:usersslug) and [`/users/email/:email`](doc:usersemailemail) are **Read** requests. * Can only use the [**include**](doc:include) parameter.
{"__v":21,"_id":"56582bf12498a10d006a255f","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"Ghost uses oAuth Client Authentication, as defined in [RFC6749 2.3](https://tools.ietf.org/html/rfc6749#section-2.3) such that public clients can authenticate with the Ghost JSON API.\n\nThis allows clients which are not able to keep information confidential (such as an API token), to still authenticate with the API using a `client_id` and `client_secret`. Specifically, this permits access for client-side or browser based JavaScript applications, which are not secure.\n\n## Making requests\n\nThe easiest way to make requests to the API is to include the `ghost.url.api()` utility. This is available by default in your theme, and can be easily included onto any other website as explain in this [tutorial](http://api.ghost.org/v0.1/docs/ajax-calls-from-an-external-website). \n\nRequests to public endpoints must include both the `client_id` and the `client_secret` as query parameters. Without these parameters, you will receive a 401 error.\n\nAn example request would look like `/ghost/api/v0.1/posts?client_id=ghost_frontend&client_secret=123456abcdef`.\n\nIf you include the correct `client_id` and `client_secret` and still get a 401 error, chances are that you are running into an issue with making a request from an untrusted origin. Please see the section on [client restrictions](#client-restrictions) below.\n\nTo find the `client_id` and `client_secret` for your blog please see the section on [available clients](#available-clients) below.\n\n## Available Clients\n\nBy default, Ghost has two clients:\n\n- `ghost-admin` is used by the admin panel to authenticate with the API so that it is then able to permit a user to login. This should not be used for any other purposes.\n\n- `ghost-frontend` is provided for use in a theme to perform Ajax queries against the Public API. \n\nThese clients exist in the `clients` table of the database. The credentials can be found by querying the database, or more easily by viewing the source for a page served on your blog and inspecting the `<script>` tags. If you're making a request from a theme, you should use [`ghost.url.api()`](http://themes.ghost.org/docs/ghost-url-api) to add the credentials, rather than doing so manually.\n\nIf you want to make a request from an external site, e.g. if your blog lives at blog.mysite.com, and you want to do an ajax request from mysite.com to get the latest posts, this can be done by adding the [`ghost.url.api()`](http://themes.ghost.org/docs/ghost-url-api) utility, however you will need to add a new entry into the `client_trusted_domains` table of your database. There's a step-by-step guide  to updating the database and including the api utility in [this tutorial](http://api.ghost.org/v0.1/docs/ajax-calls-from-an-external-website). \n\n\n## Client Restrictions\n\nAs the `client_id` and `client_secret` are not private information, requests using this method of authentication are restricted based on the origin of the request. This means the request must come from a URL that the Ghost blog recognises or the request will not be authorised.\n\nIf you attempt to access the API using client authentication, from a URL that the Ghost blog does not recognise, you will receive an error: **Access Denied from url: someurl.com. Please use the url configured in config.js**.\n\nIf, for example, you'd like to add an Ajax request to a subdomain, or parent domain of your blog, then it is possible to add extra domains for the `ghost-frontend` by adding the domain to the `client_trusted_domains` table. This should only be done for web properties that you have control over. \n\nIf you have 3rd party web properties that you'd also like to authorise to make API requests, it is recommended that you setup a new client for each one. This makes it easy to revoke access should there be a problem.","category":"55a92c6d27a17d2100525282","createdAt":"2015-11-27T10:09:53.576Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":3,"project":"543023ed7d487022005b3ff8","slug":"client-authentication","sync_unique":"","title":"Client Authentication","type":"basic","updates":["566b846203870a0d008ee7a5"],"user":"542c5cfcddd3190e00228849","version":"543033227d487022005b4032","childrenPages":[]}

Client Authentication


Ghost uses oAuth Client Authentication, as defined in [RFC6749 2.3](https://tools.ietf.org/html/rfc6749#section-2.3) such that public clients can authenticate with the Ghost JSON API. This allows clients which are not able to keep information confidential (such as an API token), to still authenticate with the API using a `client_id` and `client_secret`. Specifically, this permits access for client-side or browser based JavaScript applications, which are not secure. ## Making requests The easiest way to make requests to the API is to include the `ghost.url.api()` utility. This is available by default in your theme, and can be easily included onto any other website as explain in this [tutorial](http://api.ghost.org/v0.1/docs/ajax-calls-from-an-external-website). Requests to public endpoints must include both the `client_id` and the `client_secret` as query parameters. Without these parameters, you will receive a 401 error. An example request would look like `/ghost/api/v0.1/posts?client_id=ghost_frontend&client_secret=123456abcdef`. If you include the correct `client_id` and `client_secret` and still get a 401 error, chances are that you are running into an issue with making a request from an untrusted origin. Please see the section on [client restrictions](#client-restrictions) below. To find the `client_id` and `client_secret` for your blog please see the section on [available clients](#available-clients) below. ## Available Clients By default, Ghost has two clients: - `ghost-admin` is used by the admin panel to authenticate with the API so that it is then able to permit a user to login. This should not be used for any other purposes. - `ghost-frontend` is provided for use in a theme to perform Ajax queries against the Public API. These clients exist in the `clients` table of the database. The credentials can be found by querying the database, or more easily by viewing the source for a page served on your blog and inspecting the `<script>` tags. If you're making a request from a theme, you should use [`ghost.url.api()`](http://themes.ghost.org/docs/ghost-url-api) to add the credentials, rather than doing so manually. If you want to make a request from an external site, e.g. if your blog lives at blog.mysite.com, and you want to do an ajax request from mysite.com to get the latest posts, this can be done by adding the [`ghost.url.api()`](http://themes.ghost.org/docs/ghost-url-api) utility, however you will need to add a new entry into the `client_trusted_domains` table of your database. There's a step-by-step guide to updating the database and including the api utility in [this tutorial](http://api.ghost.org/v0.1/docs/ajax-calls-from-an-external-website). ## Client Restrictions As the `client_id` and `client_secret` are not private information, requests using this method of authentication are restricted based on the origin of the request. This means the request must come from a URL that the Ghost blog recognises or the request will not be authorised. If you attempt to access the API using client authentication, from a URL that the Ghost blog does not recognise, you will receive an error: **Access Denied from url: someurl.com. Please use the url configured in config.js**. If, for example, you'd like to add an Ajax request to a subdomain, or parent domain of your blog, then it is possible to add extra domains for the `ghost-frontend` by adding the domain to the `client_trusted_domains` table. This should only be done for web properties that you have control over. If you have 3rd party web properties that you'd also like to authorise to make API requests, it is recommended that you setup a new client for each one. This makes it easy to revoke access should there be a problem.
Ghost uses oAuth Client Authentication, as defined in [RFC6749 2.3](https://tools.ietf.org/html/rfc6749#section-2.3) such that public clients can authenticate with the Ghost JSON API. This allows clients which are not able to keep information confidential (such as an API token), to still authenticate with the API using a `client_id` and `client_secret`. Specifically, this permits access for client-side or browser based JavaScript applications, which are not secure. ## Making requests The easiest way to make requests to the API is to include the `ghost.url.api()` utility. This is available by default in your theme, and can be easily included onto any other website as explain in this [tutorial](http://api.ghost.org/v0.1/docs/ajax-calls-from-an-external-website). Requests to public endpoints must include both the `client_id` and the `client_secret` as query parameters. Without these parameters, you will receive a 401 error. An example request would look like `/ghost/api/v0.1/posts?client_id=ghost_frontend&client_secret=123456abcdef`. If you include the correct `client_id` and `client_secret` and still get a 401 error, chances are that you are running into an issue with making a request from an untrusted origin. Please see the section on [client restrictions](#client-restrictions) below. To find the `client_id` and `client_secret` for your blog please see the section on [available clients](#available-clients) below. ## Available Clients By default, Ghost has two clients: - `ghost-admin` is used by the admin panel to authenticate with the API so that it is then able to permit a user to login. This should not be used for any other purposes. - `ghost-frontend` is provided for use in a theme to perform Ajax queries against the Public API. These clients exist in the `clients` table of the database. The credentials can be found by querying the database, or more easily by viewing the source for a page served on your blog and inspecting the `<script>` tags. If you're making a request from a theme, you should use [`ghost.url.api()`](http://themes.ghost.org/docs/ghost-url-api) to add the credentials, rather than doing so manually. If you want to make a request from an external site, e.g. if your blog lives at blog.mysite.com, and you want to do an ajax request from mysite.com to get the latest posts, this can be done by adding the [`ghost.url.api()`](http://themes.ghost.org/docs/ghost-url-api) utility, however you will need to add a new entry into the `client_trusted_domains` table of your database. There's a step-by-step guide to updating the database and including the api utility in [this tutorial](http://api.ghost.org/v0.1/docs/ajax-calls-from-an-external-website). ## Client Restrictions As the `client_id` and `client_secret` are not private information, requests using this method of authentication are restricted based on the origin of the request. This means the request must come from a URL that the Ghost blog recognises or the request will not be authorised. If you attempt to access the API using client authentication, from a URL that the Ghost blog does not recognise, you will receive an error: **Access Denied from url: someurl.com. Please use the url configured in config.js**. If, for example, you'd like to add an Ajax request to a subdomain, or parent domain of your blog, then it is possible to add extra domains for the `ghost-frontend` by adding the domain to the `client_trusted_domains` table. This should only be done for web properties that you have control over. If you have 3rd party web properties that you'd also like to authorise to make API requests, it is recommended that you setup a new client for each one. This makes it easy to revoke access should there be a problem.
{"__v":15,"_id":"54b7124d1fcbe21f007c3bbe","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"Currently in order to make HTTP requests against this API, you must first obtain your current Bearer Token. In the future this should be possible using OAuth.\n\nHere are steps that can be used to obtain your Bearer Token, along with an example of using this token to make an actual API request using Postman.\n\n- Start your local or remote Ghost server.\n- Open your browser’s developer tools to inspect network traffic (Chrome dev tools was used in this example).\n- Login to the Ghost admin panel while capturing network traffic.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/oqJNwK5QPaykhjlcamgx_ghost-sign-in.png\",\n        \"ghost-sign-in.png\",\n        \"1218\",\n        \"263\",\n        \"#65abe0\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n- Inspect the HTTP request in the Network tab that was made to the ghost/api/v.0.1/notifications endpoint as shown. This request is made automatically upon initial login.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ls8RN9LpSiyPTeiKak7x_initial-login-requests.png\",\n        \"initial-login-requests.png\",\n        \"2554\",\n        \"952\",\n        \"#e4352d\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n- Note the Authorization header located in the Request Headers section of the request inspector. The text (i.e., header value) that starts with Bearer … is your current Bearer Token. Copy this value.\n- Open postman or a similar HTTP request helper and enter one of Ghost’s API endpoints. **Note** that http://localhost:2368/ghost/api/v0.1/posts was used in this example, which retrieves an array of all available posts.\n- Add the Bearer Token to the request in one of the following ways\n  - Add a Header before making the request, with the Header key set to Authorization and the value set to the Bearer Token that you copied previously. **Note** that you must include this header to authenticate with the API and receive a valid response.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/89A78TBXRIOnoKxLy5NV_postman-get-posts.png\",\n        \"postman-get-posts.png\",\n        \"2552\",\n        \"1048\",\n        \"#27428f\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n  - Add a query/URL parameter with the key set to access_token and the value set to the Bearer Token, but without including the word 'Bearer'\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/hdBeCehcRZCnt5L6dKUw_postman-get-posts-query.png\",\n        \"postman-get-posts-query.png\",\n        \"2558\",\n        \"1338\",\n        \"#2b3a6a\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n- Send the request and you should get a valid response (HTTP Status 200) from the Ghost API server. In this case, the API returned the requested array of posts given the endpoint used.\n\nThat's it! You should now be able to make API requests to all available endpoints. Refer to the latest API documentation (https://github.com/TryGhost/Ghost/wiki/%5BWIP%5D-API-Documentation#endpoints) for the latest endpoint details, or feel free to inspect the source code for the most complete and up-to-date endpoint information.\n\n**NOTE:** If you are trying to make HTTP requests to the API and receive an authorization error, check to make sure that you are using the correct Bearer Token as per the instructions above.","category":"55a92c6d27a17d2100525282","createdAt":"2015-01-15T01:05:17.141Z","excerpt":"How to utilise user auth to make private API requests","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"project":"543023ed7d487022005b3ff8","slug":"user-authentication","sync_unique":"","title":"User Authentication","type":"basic","updates":[],"user":"54b1b8d8216cfa1400f21a24","version":"543033227d487022005b4032","childrenPages":[]}

User Authentication

How to utilise user auth to make private API requests

Currently in order to make HTTP requests against this API, you must first obtain your current Bearer Token. In the future this should be possible using OAuth. Here are steps that can be used to obtain your Bearer Token, along with an example of using this token to make an actual API request using Postman. - Start your local or remote Ghost server. - Open your browser’s developer tools to inspect network traffic (Chrome dev tools was used in this example). - Login to the Ghost admin panel while capturing network traffic. [block:image] { "images": [ { "image": [ "https://files.readme.io/oqJNwK5QPaykhjlcamgx_ghost-sign-in.png", "ghost-sign-in.png", "1218", "263", "#65abe0", "" ] } ] } [/block] - Inspect the HTTP request in the Network tab that was made to the ghost/api/v.0.1/notifications endpoint as shown. This request is made automatically upon initial login. [block:image] { "images": [ { "image": [ "https://files.readme.io/ls8RN9LpSiyPTeiKak7x_initial-login-requests.png", "initial-login-requests.png", "2554", "952", "#e4352d", "" ] } ] } [/block] - Note the Authorization header located in the Request Headers section of the request inspector. The text (i.e., header value) that starts with Bearer … is your current Bearer Token. Copy this value. - Open postman or a similar HTTP request helper and enter one of Ghost’s API endpoints. **Note** that http://localhost:2368/ghost/api/v0.1/posts was used in this example, which retrieves an array of all available posts. - Add the Bearer Token to the request in one of the following ways - Add a Header before making the request, with the Header key set to Authorization and the value set to the Bearer Token that you copied previously. **Note** that you must include this header to authenticate with the API and receive a valid response. [block:image] { "images": [ { "image": [ "https://files.readme.io/89A78TBXRIOnoKxLy5NV_postman-get-posts.png", "postman-get-posts.png", "2552", "1048", "#27428f", "" ] } ] } [/block] - Add a query/URL parameter with the key set to access_token and the value set to the Bearer Token, but without including the word 'Bearer' [block:image] { "images": [ { "image": [ "https://files.readme.io/hdBeCehcRZCnt5L6dKUw_postman-get-posts-query.png", "postman-get-posts-query.png", "2558", "1338", "#2b3a6a", "" ] } ] } [/block] - Send the request and you should get a valid response (HTTP Status 200) from the Ghost API server. In this case, the API returned the requested array of posts given the endpoint used. That's it! You should now be able to make API requests to all available endpoints. Refer to the latest API documentation (https://github.com/TryGhost/Ghost/wiki/%5BWIP%5D-API-Documentation#endpoints) for the latest endpoint details, or feel free to inspect the source code for the most complete and up-to-date endpoint information. **NOTE:** If you are trying to make HTTP requests to the API and receive an authorization error, check to make sure that you are using the correct Bearer Token as per the instructions above.
Currently in order to make HTTP requests against this API, you must first obtain your current Bearer Token. In the future this should be possible using OAuth. Here are steps that can be used to obtain your Bearer Token, along with an example of using this token to make an actual API request using Postman. - Start your local or remote Ghost server. - Open your browser’s developer tools to inspect network traffic (Chrome dev tools was used in this example). - Login to the Ghost admin panel while capturing network traffic. [block:image] { "images": [ { "image": [ "https://files.readme.io/oqJNwK5QPaykhjlcamgx_ghost-sign-in.png", "ghost-sign-in.png", "1218", "263", "#65abe0", "" ] } ] } [/block] - Inspect the HTTP request in the Network tab that was made to the ghost/api/v.0.1/notifications endpoint as shown. This request is made automatically upon initial login. [block:image] { "images": [ { "image": [ "https://files.readme.io/ls8RN9LpSiyPTeiKak7x_initial-login-requests.png", "initial-login-requests.png", "2554", "952", "#e4352d", "" ] } ] } [/block] - Note the Authorization header located in the Request Headers section of the request inspector. The text (i.e., header value) that starts with Bearer … is your current Bearer Token. Copy this value. - Open postman or a similar HTTP request helper and enter one of Ghost’s API endpoints. **Note** that http://localhost:2368/ghost/api/v0.1/posts was used in this example, which retrieves an array of all available posts. - Add the Bearer Token to the request in one of the following ways - Add a Header before making the request, with the Header key set to Authorization and the value set to the Bearer Token that you copied previously. **Note** that you must include this header to authenticate with the API and receive a valid response. [block:image] { "images": [ { "image": [ "https://files.readme.io/89A78TBXRIOnoKxLy5NV_postman-get-posts.png", "postman-get-posts.png", "2552", "1048", "#27428f", "" ] } ] } [/block] - Add a query/URL parameter with the key set to access_token and the value set to the Bearer Token, but without including the word 'Bearer' [block:image] { "images": [ { "image": [ "https://files.readme.io/hdBeCehcRZCnt5L6dKUw_postman-get-posts-query.png", "postman-get-posts-query.png", "2558", "1338", "#2b3a6a", "" ] } ] } [/block] - Send the request and you should get a valid response (HTTP Status 200) from the Ghost API server. In this case, the API returned the requested array of posts given the endpoint used. That's it! You should now be able to make API requests to all available endpoints. Refer to the latest API documentation (https://github.com/TryGhost/Ghost/wiki/%5BWIP%5D-API-Documentation#endpoints) for the latest endpoint details, or feel free to inspect the source code for the most complete and up-to-date endpoint information. **NOTE:** If you are trying to make HTTP requests to the API and receive an authorization error, check to make sure that you are using the correct Bearer Token as per the instructions above.
{"__v":8,"_id":"54aad2919bb00c0b00cb8a6a","api":{"auth":"required","examples":{"codes":[{"name":"jQuery.ajax","code":"$.get(ghost.url.api('posts', {limit: 2})).done(function (data){\n\tconsole.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});","language":"javascript"},{"code":"api.posts.browse({limit: 2});","language":"javascript","name":"Internal"},{"name":"Handlebars","code":"{{#get \"posts\" limit=\"2\"}}{{/get}}","language":"handlebars"}]},"params":[{"_id":"54aad2919bb00c0b00cb8a6b","required":false,"desc":"Include related data, possible values: tags, author,","default":"","type":"string","name":"include","in":"query"},{"_id":"54aadc9d99f6581600167c6d","required":false,"desc":"How many posts to retrieve, use `all` to retrieve all posts","default":"15","type":"string","name":"limit","in":"query"},{"_id":"54aadc9d99f6581600167c6c","required":false,"desc":"Which page of paginated results to retrieve","default":"1","type":"string","name":"page","in":"query"},{"_id":"563a419450bf950d00e097c7","required":false,"desc":"Choose which field to order by and direction of ordering (asc or desc)","default":"published_at desc","type":"string","name":"order","in":"query"},{"_id":"563a462dc63a22190018dc8c","required":false,"desc":"Choose which fields you want to include in collection","default":"","type":"string","name":"fields","in":"query"},{"_id":"563a462dc63a22190018dc8b","required":false,"desc":"Use Ghost Query Language to build complex query","default":"","type":"string","name":"filter","in":"query"},{"_id":"5659b50a2892180d00eb583e","required":false,"desc":"**id** or **slug** changes query to a **read** request","default":"","type":"string","name":"resource field","in":"query"}],"results":{"codes":[{"name":"","code":"{\n  \"posts\":[{\n    \"id\":1,\n    \"uuid\":\"bc0a0924-b49c-45c8-897d-728f6acba7c9\",\n    \"title\":\"Welcome to Ghost\",\n    \"slug\":\"welcome-to-ghost\",\n    \"markdown\":\"You're live! Nice. We've put together a little post to introduce you to the Ghost editor and get you started. You can manage your content by signing in to the admin area at `<your blog URL>/ghost/`. When you arrive, you can select this post from a list on the left and see a preview of it on the right. Click the little pencil icon at the top of the preview to edit this post and read the next section!\\n\\n## Getting Started\\n\\nGhost uses something called Markdown for writing. Essentially, it's a shorthand way to manage your post formatting as you write!\",\n    \"html\":\"<p>You're live! Nice. We've put together a little post to introduce you to the Ghost editor and get you started. You can manage your content by signing in to the admin area at <code>&lt;your blog URL&gt;/ghost/</code>. When you arrive, you can select this post from a list on the left and see a preview of it on the right. Click the little pencil icon at the top of the preview to edit this post and read the next section!</p>\\n\\n<h2 id=\\\"gettingstarted\\\">Getting Started</h2>\\n\\n<p>Ghost uses something called Markdown for writing. Essentially, it's a shorthand way to manage your post formatting as you write!</p>\",\n    \"image\":null,\n    \"featured\":false,\n    \"page\":false,\n    \"status\":\"published\",\n    \"language\":\"en_US\",\n    \"meta_title\":null,\n    \"meta_description\":null,\n    \"created_at\":\"2014-11-17T19:02:27.147Z\",\n    \"created_by\":1,\n    \"updated_at\":\"2014-11-17T19:02:27.147Z\",\n    \"updated_by\":1,\n    \"published_at\":\"2014-11-17T19:02:27.173Z\",\n    \"published_by\":1,\n    \"author\":1,\n    \"url\":\"/welcome-to-ghost/\"\n  }, {\n    \"id\":2,\n    \"uuid\":\"ac0a0374-a43c-15c4-391b-128d6bbba7c5\",\n    \"title\":\"Lorem Ipsum Dolor\",\n    \"slug\":\"lorem-ipsum-dolor\",\n    \"markdown\":\"Lorem ipsum dolor sit amet, consectetaur adipisicing elit, sed do eiusmod\\n\\n\",\n    \"html\":\"<p>Lorem ipsum dolor sit amet, consectetaur adipisicing elit, sed do eiusmod</p>\",\n    \"image\":null,\n    \"featured\":false,\n    \"page\":false,\n    \"status\":\"published\",\n    \"language\":\"en_US\",\n    \"meta_title\":null,\n    \"meta_description\":null,\n    \"created_at\":\"2014-11-18T19:02:27.147Z\",\n    \"created_by\":1,\n    \"updated_at\":\"2014-11-18T19:02:27.147Z\",\n    \"updated_by\":1,\n    \"published_at\":\"2014-11-18T19:02:27.173Z\",\n    \"published_by\":1,\n    \"author\":1,\n    \"url\":\"/lorem-ipsum-dolor/\"\n  }],\n  \"meta\":{\n    \"pagination\":{\n      \"page\":1,\n      \"limit\":2,\n      \"pages\":1,\n      \"total\":1,\n      \"next\":null,\n      \"prev\":null\n    }\n  }\n}","language":"json","status":200}]},"settings":"","url":"/posts/"},"body":"The posts endpoint allows you to browse all published posts on a particular blog. By default it returns a paginated set of 15 published posts in reverse chronological order (newest first) and excludes pages.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /posts/\",\n      \"language\": \"http\",\n      \"name\": \"HTTP\"\n    },\n    {\n      \"code\": \"$.get(ghost.url.api('posts')).done(function (data){\\n  console.log('posts', data.posts);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"api.posts.browse();\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"{{#get \\\"posts\\\"}}\\n  {{#foreach posts}}\\n    // do something\\n  {{/foreach}}\\n{{/get}}\",\n      \"language\": \"handlebars\",\n      \"name\": \"Handlebars\"\n    }\n  ]\n}\n[/block]\nYou can further order/filter your collection using the allowed parameters above. These are discussed in more detail in the [**parameters section**](doc:parameters).\n\nSpecifying a *slug* or *id* changes the query to a **read** request, in this case only the [**include**](doc:include) parameter is valid.","category":"55a92e7ecf45e1390093f32b","createdAt":"2015-01-05T18:06:09.555Z","editedParams":true,"editedParams2":true,"excerpt":"Fetch a paginated set of published posts","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"543023ed7d487022005b3ff8","slug":"posts","sync_unique":"","title":"/posts/","type":"get","updates":[],"user":"542c5cfcddd3190e00228849","version":"543033227d487022005b4032","childrenPages":[]}

get/posts/

Fetch a paginated set of published posts

Query Params

include:
string
Include related data, possible values: tags, author,
limit:
string15
How many posts to retrieve, use `all` to retrieve all posts
page:
string1
Which page of paginated results to retrieve
order:
stringpublished_at desc
Choose which field to order by and direction of ordering (asc or desc)
fields:
string
Choose which fields you want to include in collection
filter:
string
Use Ghost Query Language to build complex query
resource:
string
**id** or **slug** changes query to a **read** request
The posts endpoint allows you to browse all published posts on a particular blog. By default it returns a paginated set of 15 published posts in reverse chronological order (newest first) and excludes pages. [block:code] { "codes": [ { "code": "GET /posts/", "language": "http", "name": "HTTP" }, { "code": "$.get(ghost.url.api('posts')).done(function (data){\n console.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.posts.browse();", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"posts\"}}\n {{#foreach posts}}\n // do something\n {{/foreach}}\n{{/get}}", "language": "handlebars", "name": "Handlebars" } ] } [/block] You can further order/filter your collection using the allowed parameters above. These are discussed in more detail in the [**parameters section**](doc:parameters). Specifying a *slug* or *id* changes the query to a **read** request, in this case only the [**include**](doc:include) parameter is valid.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



The posts endpoint allows you to browse all published posts on a particular blog. By default it returns a paginated set of 15 published posts in reverse chronological order (newest first) and excludes pages. [block:code] { "codes": [ { "code": "GET /posts/", "language": "http", "name": "HTTP" }, { "code": "$.get(ghost.url.api('posts')).done(function (data){\n console.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.posts.browse();", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"posts\"}}\n {{#foreach posts}}\n // do something\n {{/foreach}}\n{{/get}}", "language": "handlebars", "name": "Handlebars" } ] } [/block] You can further order/filter your collection using the allowed parameters above. These are discussed in more detail in the [**parameters section**](doc:parameters). Specifying a *slug* or *id* changes the query to a **read** request, in this case only the [**include**](doc:include) parameter is valid.
{"__v":5,"_id":"55a7a8393efe0c2f0074ca92","api":{"auth":"required","examples":{"codes":[{"name":"jQuery.ajax","code":"$.get(ghost.url.api('posts/5'})).done(function (data){\n\tconsole.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});\n\n// Alternatively you can pass the id as a parameter with the same result\n$.get(ghost.url.api('posts', {id: 5})).done(function (data){\n\tconsole.log('posts', data.posts);\t\n}).fail(function (err){\n\tconsole.log(err);\n});","language":"javascript"},{"code":"api.posts.read({id: 5});","language":"javascript","name":"Internal"},{"code":"{{#get \"posts\" id=\"5\"}}{{/get}}","language":"handlebars","name":"Handlebars"}]},"params":[{"_id":"55a7a8c93efe0c2f0074ca96","required":false,"desc":"Include related data, possible values: tags, author","default":"","type":"string","name":"include","in":"query"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"posts\":[{\n    \"id\":5,\n    \"uuid\":\"bc0a0924-b49c-45c8-897d-728f6acba7c9\",\n    \"title\":\"Welcome to Ghost\",\n    \"slug\":\"welcome-to-ghost\",\n    \"markdown\":\"You're live! Nice. We've put together a little post to introduce you to the Ghost editor and get you started. You can manage your content by signing in to the admin area at `<your blog URL>/ghost/`. When you arrive, you can select this post from a list on the left and see a preview of it on the right. Click the little pencil icon at the top of the preview to edit this post and read the next section!\\n\\n## Getting Started\\n\\nGhost uses something called Markdown for writing. Essentially, it's a shorthand way to manage your post formatting as you write!\",\n    \"html\":\"<p>You're live! Nice. We've put together a little post to introduce you to the Ghost editor and get you started. You can manage your content by signing in to the admin area at <code>&lt;your blog URL&gt;/ghost/</code>. When you arrive, you can select this post from a list on the left and see a preview of it on the right. Click the little pencil icon at the top of the preview to edit this post and read the next section!</p>\\n\\n<h2 id=\\\"gettingstarted\\\">Getting Started</h2>\\n\\n<p>Ghost uses something called Markdown for writing. Essentially, it's a shorthand way to manage your post formatting as you write!</p>\",\n    \"image\":null,\n    \"featured\":false,\n    \"page\":false,\n    \"status\":\"published\",\n    \"language\":\"en_US\",\n    \"meta_title\":null,\n    \"meta_description\":null,\n    \"created_at\":\"2014-11-17T19:02:27.147Z\",\n    \"created_by\":1,\n    \"updated_at\":\"2014-11-17T19:02:27.147Z\",\n    \"updated_by\":1,\n    \"published_at\":\"2014-11-17T19:02:27.173Z\",\n    \"published_by\":1,\n    \"author\":1,\n    \"url\":\"/welcome-to-ghost/\"\n  }]\n}","name":""}]},"settings":"","url":"/posts/:id"},"body":"This endpoint allows you to read a specific post based on its id.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/posts/:id\\n\\nE.g /posts/3\",\n      \"language\": \"http\"\n    },\n    {\n      \"code\": \"$.get(ghost.url.api('posts/5')).done(function (data){\\n\\tconsole.log('posts', data.posts);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"api.posts.read({id: 5});\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"{{#get \\\"posts\\\" id=\\\"5\\\" }}{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]","category":"55a92e7ecf45e1390093f32b","createdAt":"2015-07-16T12:48:57.693Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"543023ed7d487022005b3ff8","slug":"postsid","sync_unique":"","title":"/posts/:id","type":"get","updates":[],"user":"542c5cfcddd3190e00228849","version":"543033227d487022005b4032","childrenPages":[]}

get/posts/:id


Query Params

include:
string
Include related data, possible values: tags, author
This endpoint allows you to read a specific post based on its id. [block:code] { "codes": [ { "code": "/posts/:id\n\nE.g /posts/3", "language": "http" }, { "code": "$.get(ghost.url.api('posts/5')).done(function (data){\n\tconsole.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.posts.read({id: 5});", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"posts\" id=\"5\" }}{{/get}}", "language": "handlebars" } ] } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



This endpoint allows you to read a specific post based on its id. [block:code] { "codes": [ { "code": "/posts/:id\n\nE.g /posts/3", "language": "http" }, { "code": "$.get(ghost.url.api('posts/5')).done(function (data){\n\tconsole.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.posts.read({id: 5});", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"posts\" id=\"5\" }}{{/get}}", "language": "handlebars" } ] } [/block]
{"__v":2,"_id":"5641f915b0dc090d00f883f4","api":{"auth":"required","examples":{"codes":[{"language":"javascript","code":"$.get(ghost.url.api('posts/slug/welcome-to-ghost')).done(function (data){\n\tconsole.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});\n        \n// Alternatively you can specify slug as a parameter to the posts endpoint       \n$.get(ghost.url.api('posts', {slug: 'welcome-to-ghost'})).done(function (data){\n\tconsole.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});","name":"jQuery.ajax"},{"name":"Internal","language":"javascript","code":"api.posts.read({slug: \"welcome-to-ghost\", include: [author, tags]});"},{"name":"Handlebars","language":"handlebars","code":"{{#get \"posts\" slug=\"welcome-to-ghost\" include=\"author,tags\"}}{{/get}}"}]},"params":[{"_id":"5659bb08314e600d00292c96","required":false,"desc":"Include related data, possible values: tags, author","default":"","type":"string","name":"include","in":"query"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"posts\":[{\n    \"id\":5,\n    \"uuid\":\"bc0a0924-b49c-45c8-897d-728f6acba7c9\",\n    \"title\":\"Welcome to Ghost\",\n    \"slug\":\"welcome-to-ghost\",\n    \"markdown\":\"You're live! Nice. We've put together a little post to introduce you to the Ghost editor and get you started. You can manage your content by signing in to the admin area at `<your blog URL>/ghost/`. When you arrive, you can select this post from a list on the left and see a preview of it on the right. Click the little pencil icon at the top of the preview to edit this post and read the next section!\\n\\n## Getting Started\\n\\nGhost uses something called Markdown for writing. Essentially, it's a shorthand way to manage your post formatting as you write!\",\n    \"html\":\"<p>You're live! Nice. We've put together a little post to introduce you to the Ghost editor and get you started. You can manage your content by signing in to the admin area at <code>&lt;your blog URL&gt;/ghost/</code>. When you arrive, you can select this post from a list on the left and see a preview of it on the right. Click the little pencil icon at the top of the preview to edit this post and read the next section!</p>\\n\\n<h2 id=\\\"gettingstarted\\\">Getting Started</h2>\\n\\n<p>Ghost uses something called Markdown for writing. Essentially, it's a shorthand way to manage your post formatting as you write!</p>\",\n    \"image\":null,\n    \"featured\":false,\n    \"page\":false,\n    \"status\":\"published\",\n    \"language\":\"en_US\",\n    \"meta_title\":null,\n    \"meta_description\":null,\n    \"created_at\":\"2014-11-17T19:02:27.147Z\",\n    \"created_by\":1,\n    \"updated_at\":\"2014-11-17T19:02:27.147Z\",\n    \"updated_by\":1,\n    \"published_at\":\"2014-11-17T19:02:27.173Z\",\n    \"published_by\":1,\n    \"author\":1,\n    \"url\":\"/welcome-to-ghost/\"\n  }]\n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/posts/slug/:slug"},"body":"This endpoint allows you to read a specific post based on its slug.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/posts/slug/:slug\\n\\nE.g /posts/slug/welcome-to-ghost\",\n      \"language\": \"http\"\n    },\n    {\n      \"code\": \"$.get(ghost.url.api('posts', {slug: 'welcome-to-ghost'})).done(function (data){\\n\\tconsole.log('posts', data.posts);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"api.posts.read({slug: \\\"welcome-to-ghost\\\"});\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"{{#get \\\"posts\\\" slug=\\\"welcome-to-ghost\\\"}}{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]","category":"55a92e7ecf45e1390093f32b","createdAt":"2015-11-10T14:03:01.793Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"543023ed7d487022005b3ff8","slug":"postsslugslug","sync_unique":"","title":"/posts/slug/:slug","type":"get","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

get/posts/slug/:slug


Query Params

include:
string
Include related data, possible values: tags, author
This endpoint allows you to read a specific post based on its slug. [block:code] { "codes": [ { "code": "/posts/slug/:slug\n\nE.g /posts/slug/welcome-to-ghost", "language": "http" }, { "code": "$.get(ghost.url.api('posts', {slug: 'welcome-to-ghost'})).done(function (data){\n\tconsole.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.posts.read({slug: \"welcome-to-ghost\"});", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"posts\" slug=\"welcome-to-ghost\"}}{{/get}}", "language": "handlebars" } ] } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



This endpoint allows you to read a specific post based on its slug. [block:code] { "codes": [ { "code": "/posts/slug/:slug\n\nE.g /posts/slug/welcome-to-ghost", "language": "http" }, { "code": "$.get(ghost.url.api('posts', {slug: 'welcome-to-ghost'})).done(function (data){\n\tconsole.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.posts.read({slug: \"welcome-to-ghost\"});", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"posts\" slug=\"welcome-to-ghost\"}}{{/get}}", "language": "handlebars" } ] } [/block]
{"__v":6,"_id":"563b509ae951f60d000b44da","api":{"auth":"required","examples":{"codes":[{"language":"javascript","code":"$.get(ghost.url.api('tags')).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});","name":"jQuery.ajax"},{"name":"Internal","language":"javascript","code":"api.tags.browse({limit: 2});"},{"name":"Handlebars","language":"handlebars","code":"{{#get \"tags\" limit=\"2\"}}\n  {{#foreach tags}}\n    // do something\n  {{/foreach}}\n{{/get}}"}]},"params":[{"_id":"5641c0d29417b40d00c0fbef","required":false,"desc":"How many tags to retrieve, use `all` to retrieve all tags","default":"15","type":"string","name":"limit","in":"query"},{"_id":"5641c18a49a29c0d00886cbc","required":false,"desc":"Which page of paginated results to retrieve","default":"1","type":"string","name":"page","in":"query"},{"_id":"5641c9a19f4ed50d008be091","required":false,"desc":"Choose which field to order by and direction of ordering (asc or desc)","default":"nil","type":"string","name":"order","in":"query"},{"_id":"5659b9ae4158430d00f05da8","required":false,"desc":"count.posts","default":"","type":"string","name":"include","in":"query"},{"_id":"5641c9a19f4ed50d008be090","required":false,"desc":"Choose which resource fields you want to include in collection","default":"nil","type":"string","name":"fields","in":"query"},{"_id":"5641c9a19f4ed50d008be08f","required":false,"desc":"Use Ghost Query Language to build complex query","default":"","type":"string","name":"filter","in":"query"},{"_id":"5659b662f80fb10d0057a917","default":"","desc":"**id** changes query to a **read** request","name":"resource field","required":false,"type":"string","in":"query"}],"results":{"codes":[{"name":"","code":"{\n  \"tags\":[{\n    \"id\":1,\n    \"uuid\":\"ec3a0924-a59c-45c8-817d-428f6acba7c4\",\n    \"name\":\"Getting Started\",\n    \"slug\":\"getting-started\",\n    \"hidden\": false,\n    \"parent\": null,\n    \"image\":null,\n    \"meta_title\":null,\n    \"meta_description\":null,\n    \"created_at\":\"2014-11-17T19:02:27.147Z\",\n    \"created_by\":1,\n    \"updated_at\":\"2014-11-17T19:02:27.147Z\",\n    \"updated_by\":1\n  }, {\n    \"id\":2,\n    \"uuid\":\"ac2a0927-a59b-15c8-613a-768f6acba7b2\",\n    \"name\":\"Using Ghost\",\n    \"slug\":\"using-ghost\",\n    \"hidden\": false,\n    \"parent\": null,\n    \"image\":null,\n    \"meta_title\":null,\n    \"meta_description\":null,\n    \"created_at\":\"2014-11-18T19:02:27.147Z\",\n    \"created_by\":1,\n    \"updated_at\":\"2014-11-18T19:02:27.147Z\",\n    \"updated_by\":1\n  }],\n  \"meta\":{\n    \"pagination\":{\n      \"page\":1,\n      \"limit\":2,\n      \"pages\":1,\n      \"total\":1,\n      \"next\":null,\n      \"prev\":null\n    }\n  }\n}","language":"json","status":200}]},"settings":"","url":"/tags/"},"body":"The tags endpoints allow you to browse all tags on a particular blog. You can then use the parameters to to specify which data to collect. By default it returns a paginated set of 15 tags in order of database row (first row first).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /tags/\",\n      \"language\": \"http\"\n    },\n    {\n      \"code\": \"$.get(ghost.url.api('tags')).done(function (data){\\n\\tconsole.log('tags', data.tags);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"api.tags.browse();\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"{{#get \\\"tags\\\"}}{{/get}}\",\n      \"language\": \"handlebars\",\n      \"name\": \"Handlebars\"\n    }\n  ]\n}\n[/block]\nYou can further filter your collection using the allowed parameters above. These are discussed in more detail in the [**parameters section**](doc:parameters)\n\nSpecifying *id* changes the query to a **read** request, in this case only the [**include**](doc:include) parameter is valid.","category":"55a92e7ecf45e1390093f32b","createdAt":"2015-11-05T12:50:34.304Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"project":"543023ed7d487022005b3ff8","slug":"tags","sync_unique":"","title":"/tags/","type":"get","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

get/tags/


Query Params

limit:
string15
How many tags to retrieve, use `all` to retrieve all tags
page:
string1
Which page of paginated results to retrieve
order:
stringnil
Choose which field to order by and direction of ordering (asc or desc)
include:
string
count.posts
fields:
stringnil
Choose which resource fields you want to include in collection
filter:
string
Use Ghost Query Language to build complex query
resource:
string
**id** changes query to a **read** request
The tags endpoints allow you to browse all tags on a particular blog. You can then use the parameters to to specify which data to collect. By default it returns a paginated set of 15 tags in order of database row (first row first). [block:code] { "codes": [ { "code": "GET /tags/", "language": "http" }, { "code": "$.get(ghost.url.api('tags')).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.tags.browse();", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"tags\"}}{{/get}}", "language": "handlebars", "name": "Handlebars" } ] } [/block] You can further filter your collection using the allowed parameters above. These are discussed in more detail in the [**parameters section**](doc:parameters) Specifying *id* changes the query to a **read** request, in this case only the [**include**](doc:include) parameter is valid.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



The tags endpoints allow you to browse all tags on a particular blog. You can then use the parameters to to specify which data to collect. By default it returns a paginated set of 15 tags in order of database row (first row first). [block:code] { "codes": [ { "code": "GET /tags/", "language": "http" }, { "code": "$.get(ghost.url.api('tags')).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.tags.browse();", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"tags\"}}{{/get}}", "language": "handlebars", "name": "Handlebars" } ] } [/block] You can further filter your collection using the allowed parameters above. These are discussed in more detail in the [**parameters section**](doc:parameters) Specifying *id* changes the query to a **read** request, in this case only the [**include**](doc:include) parameter is valid.
{"__v":11,"_id":"563b50bbe951f60d000b44dc","api":{"auth":"required","examples":{"codes":[{"name":"jQuery.ajax","code":"$.get(ghost.url.api('tags/2')).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});\n        \n// Alternatively you can specify id as a parameter to the users endpoint\n$.get(ghost.url.api('tags', {id: 2})).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});","language":"javascript"},{"name":"Internal","language":"javascript","code":"api.tags.read({id: 2});"},{"language":"handlebars","code":"{{#get \"tags\" id=\"2\"}}{{/get}}","name":"Handlebars"}]},"params":[{"_id":"5659ee1a60571a0d002cd1f3","required":false,"desc":"count.posts","default":"","type":"string","name":"include","in":"query"}],"results":{"codes":[{"name":"","code":"{\n  \"tags\":[{\n    \"id\":2,\n    \"uuid\":\"ac2a0927-a59b-15c8-613a-768f6acba7b2\",\n    \"name\":\"Using Ghost\",\n    \"slug\":\"using-ghost\",\n    \"hidden\": false,\n    \"parent\": null,\n    \"image\":null,\n    \"meta_title\":null,\n    \"meta_description\":null,\n    \"created_at\":\"2014-11-18T19:02:27.147Z\",\n    \"created_by\":1,\n    \"updated_at\":\"2014-11-18T19:02:27.147Z\",\n    \"updated_by\":1\n  }]\n}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","url":"/tags/:id"},"body":"This endpoint allows you to read a specific tag based on its id.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/tags/:id\\n\\nE.g /tags/3\",\n      \"language\": \"http\"\n    },\n    {\n      \"code\": \"$.get(ghost.url.api('tags/2')).done(function (data){\\n\\tconsole.log('tags', data.tags);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"api.tags.read({id: 2});\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"{{#get \\\"tags\\\" id=\\\"2\\\"}}{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\nYou can [**include**](doc:include) count.posts for this endpoint.","category":"55a92e7ecf45e1390093f32b","createdAt":"2015-11-05T12:51:07.928Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"project":"543023ed7d487022005b3ff8","slug":"tagsid","sync_unique":"","title":"/tags/:id","type":"get","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

get/tags/:id


Query Params

include:
string
count.posts
This endpoint allows you to read a specific tag based on its id. [block:code] { "codes": [ { "code": "/tags/:id\n\nE.g /tags/3", "language": "http" }, { "code": "$.get(ghost.url.api('tags/2')).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.tags.read({id: 2});", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"tags\" id=\"2\"}}{{/get}}", "language": "handlebars" } ] } [/block] You can [**include**](doc:include) count.posts for this endpoint.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



This endpoint allows you to read a specific tag based on its id. [block:code] { "codes": [ { "code": "/tags/:id\n\nE.g /tags/3", "language": "http" }, { "code": "$.get(ghost.url.api('tags/2')).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.tags.read({id: 2});", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"tags\" id=\"2\"}}{{/get}}", "language": "handlebars" } ] } [/block] You can [**include**](doc:include) count.posts for this endpoint.
{"__v":0,"_id":"5659f3f92892180d00eb584f","api":{"auth":"required","examples":{"codes":[{"name":"jQuery.ajax","code":"$.get(ghost.url.api('tags/slug/using-ghost')).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});\n        \n// Alternatively you can specify slug as a parameter to the users endpoint\n$.get(ghost.url.api('tags', {slug: \"using-ghost\"})).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});","language":"javascript"},{"name":"Internal","language":"javascript","code":"api.tags.read({slug: \"using-ghost\"});"},{"language":"handlebars","code":"{{#get \"tags\" slug=\"using-ghost\"}}{{/get}}","name":"Handlebars"}]},"params":[{"_id":"5659ee1a60571a0d002cd1f3","required":false,"desc":"count.posts","default":"","type":"string","name":"include","in":"query"}],"results":{"codes":[{"name":"","code":"{\n  \"tags\":[{\n    \"id\":2,\n    \"uuid\":\"ac2a0927-a59b-15c8-613a-768f6acba7b2\",\n    \"name\":\"Using Ghost\",\n    \"slug\":\"using-ghost\",\n    \"hidden\": false,\n    \"parent\": null,\n    \"image\":null,\n    \"meta_title\":null,\n    \"meta_description\":null,\n    \"created_at\":\"2014-11-18T19:02:27.147Z\",\n    \"created_by\":1,\n    \"updated_at\":\"2014-11-18T19:02:27.147Z\",\n    \"updated_by\":1\n  }]\n}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","url":"/tags/slug/:slug"},"body":"This endpoint allows you to read a specific tag based on its slug.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/tags/slug/:slug\\n\\nE.g /tags/slug/using-ghost\",\n      \"language\": \"http\"\n    },\n    {\n      \"code\": \"$.get(ghost.url.api('tags/slug/using-ghost')).done(function (data){\\n\\tconsole.log('tags', data.tags);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"api.tags.read({slug: \\\"using-ghost\\\"});\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"{{#get \\\"tags\\\" slug=\\\"using-ghost\\\"}}{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\nYou can [**include**](doc:include) count.posts for this endpoint.","category":"55a92e7ecf45e1390093f32b","createdAt":"2015-11-28T18:35:37.615Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":5,"project":"543023ed7d487022005b3ff8","slug":"tagsslugslug","sync_unique":"","title":"/tags/slug/:slug","type":"get","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

get/tags/slug/:slug


Query Params

include:
string
count.posts
This endpoint allows you to read a specific tag based on its slug. [block:code] { "codes": [ { "code": "/tags/slug/:slug\n\nE.g /tags/slug/using-ghost", "language": "http" }, { "code": "$.get(ghost.url.api('tags/slug/using-ghost')).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.tags.read({slug: \"using-ghost\"});", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"tags\" slug=\"using-ghost\"}}{{/get}}", "language": "handlebars" } ] } [/block] You can [**include**](doc:include) count.posts for this endpoint.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



This endpoint allows you to read a specific tag based on its slug. [block:code] { "codes": [ { "code": "/tags/slug/:slug\n\nE.g /tags/slug/using-ghost", "language": "http" }, { "code": "$.get(ghost.url.api('tags/slug/using-ghost')).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.tags.read({slug: \"using-ghost\"});", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"tags\" slug=\"using-ghost\"}}{{/get}}", "language": "handlebars" } ] } [/block] You can [**include**](doc:include) count.posts for this endpoint.
{"__v":2,"_id":"563b50f0f9cea81900553d7b","api":{"auth":"required","examples":{"codes":[{"name":"jQuery.ajax","code":"$.get(ghost.url.api('users')).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});","language":"javascript"},{"name":"Internal","code":"api.users.browse({limit:2});","language":"javascript"},{"code":"{{#get \"users\" limit=\"2\"}}{{/get}}","language":"handlebars","name":"Handlebars"}]},"params":[{"_id":"5641e4b5b48bdf19006a4c27","required":false,"desc":"How many users to retrieve, use `all` to retrieve all users","default":"15","type":"string","name":"limit","in":"query"},{"_id":"5641e4b5b48bdf19006a4c26","required":false,"desc":"Which page of paginated results to retrieve","default":"1","type":"string","name":"page","in":"query"},{"_id":"5641e4b5b48bdf19006a4c25","required":false,"desc":"Choose which field to order by and direction of ordering (asc or desc)","default":"last_login (desc)","type":"string","name":"order","in":"query"},{"_id":"5659ba0864950b0d00e78dfb","required":false,"desc":"count.posts","default":"","type":"string","name":"include","in":"query"},{"_id":"5641e4b5b48bdf19006a4c24","required":false,"desc":"Choose which fields you want to include in collection","default":"","type":"string","name":"fields","in":"query"},{"_id":"5641e4b5b48bdf19006a4c23","required":false,"desc":"Use Ghost Query Language to build complex query","default":"","type":"string","name":"filter","in":"query"}],"results":{"codes":[{"name":"","code":"{\n  \"users\":[{\n    \"accessibility\": null,\n    \"bio\": null,\n    \"cover\": null,\n    \"created_at\": \"2014-10-11T19:02:27.147Z\",\n    \"created_by\": 1,\n    \"id\":1,\n    \"image\": null,\n    \"language\": \"en_US\",\n    \"last_login\": \"2014-11-17T19:02:27.147Z\",\n    \"location\": null,\n    \"meta_description\": null,\n    \"meta_title\": null,\n    \"name\": \"Eric Almeida\",\n    \"slug\": \"eric-almeida\",\n    \"status\":\"active\",\n    \"tour\": null,\n    \"updated_at\":\"2014-10-11T19:02:27.147Z\",\n    \"updated_by\":1,\n    \"uuid\": \"fs4a0021-b22a-33a1-531c-424e2caba3c3\",\n    \"website\": null,\n  }, {\n   \"accessibility\": null,\n    \"bio\": \"Node Developer\",\n    \"cover\": null,\n    \"created_at\": \"2014-10-18T19:02:27.147Z\",\n    \"created_by\": 1,\n    \"id\":1,\n    \"image\": null,\n    \"language\": \"en_US\",\n    \"last_login\": \"2014-11-22T19:02:27.147Z\",\n    \"location\": null,\n    \"meta_description\": null,\n    \"meta_title\": null,\n    \"name\": \"Sally Walsh\",\n    \"slug\": \"sally-walsh\",\n    \"status\":\"active\",\n    \"tour\": null,\n    \"updated_at\":\"2014-10-18T19:02:27.147Z\",\n    \"updated_by\":1,\n    \"uuid\": \"fs4a0021-b22a-33a1-531c-424e2caba3c3\",\n    \"website\": null,  \n  }],\n  \"meta\":{\n    \"pagination\":{\n      \"page\":1,\n      \"limit\":2,\n      \"pages\":1,\n      \"total\":1,\n      \"next\":null,\n      \"prev\":null\n    }\n  }\n}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","url":"/users/"},"body":"The users endpoint allows you to browse all active users on a particular blog. By default it returns a paginated set of 15 active users in descending order of last_login.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /users/\",\n      \"language\": \"http\"\n    },\n    {\n      \"code\": \"$.get(ghost.url.api('users')).done(function (data){\\n\\tconsole.log('users', data.users);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"api.users.browse();\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"{{#get \\\"users\\\"}}{{/get}}\",\n      \"language\": \"handlebars\",\n      \"name\": \"Handlebars\"\n    }\n  ]\n}\n[/block]\nYou can further order/filter your collection using the allowed parameters above. These are discussed in more detail in the [**parameters section**](doc:parameters).\n\nSpecifying *id*, *slug* or *email* changes the query to a **read** request, in this case only the [**include**](doc:include) parameter is valid.","category":"55a92e7ecf45e1390093f32b","createdAt":"2015-11-05T12:52:00.671Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":6,"project":"543023ed7d487022005b3ff8","slug":"users","sync_unique":"","title":"/users/","type":"get","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

get/users/


Query Params

limit:
string15
How many users to retrieve, use `all` to retrieve all users
page:
string1
Which page of paginated results to retrieve
order:
stringlast_login (desc)
Choose which field to order by and direction of ordering (asc or desc)
include:
string
count.posts
fields:
string
Choose which fields you want to include in collection
filter:
string
Use Ghost Query Language to build complex query
The users endpoint allows you to browse all active users on a particular blog. By default it returns a paginated set of 15 active users in descending order of last_login. [block:code] { "codes": [ { "code": "GET /users/", "language": "http" }, { "code": "$.get(ghost.url.api('users')).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.users.browse();", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"users\"}}{{/get}}", "language": "handlebars", "name": "Handlebars" } ] } [/block] You can further order/filter your collection using the allowed parameters above. These are discussed in more detail in the [**parameters section**](doc:parameters). Specifying *id*, *slug* or *email* changes the query to a **read** request, in this case only the [**include**](doc:include) parameter is valid.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



The users endpoint allows you to browse all active users on a particular blog. By default it returns a paginated set of 15 active users in descending order of last_login. [block:code] { "codes": [ { "code": "GET /users/", "language": "http" }, { "code": "$.get(ghost.url.api('users')).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.users.browse();", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"users\"}}{{/get}}", "language": "handlebars", "name": "Handlebars" } ] } [/block] You can further order/filter your collection using the allowed parameters above. These are discussed in more detail in the [**parameters section**](doc:parameters). Specifying *id*, *slug* or *email* changes the query to a **read** request, in this case only the [**include**](doc:include) parameter is valid.
{"__v":14,"_id":"563b51099e3f2225009fd29a","api":{"auth":"required","examples":{"codes":[{"language":"javascript","code":"$.get(ghost.url.api('users/1')).done(function (data){\n\tconsole.log('users', data.users);\t\n}).fail(function (err){\n\tconsole.log(err);\n});\n      \n// Alternatively you can specify id as a parameter to the users endpoint\n$.get(ghost.url.api('users', {id: 1})).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});","name":"jQuery.ajax"},{"name":"Internal","language":"javascript","code":"api.users.read({id: 1});"},{"name":"Handlebars","language":"handlebars","code":"{{#get \"users\" id=\"1\"}}{{/get}}"}]},"params":[{"_id":"5659ee892892180d00eb584d","required":false,"desc":"count.posts","default":"","type":"string","name":"include","in":"query"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"users\":[{\n    \"accessibility\": null,\n    \"bio\": null,\n    \"cover\": null,\n    \"created_at\": \"2014-10-11T19:02:27.147Z\",\n    \"created_by\": 1,\n    \"id\":1,\n    \"image\": null,\n    \"language\": \"en_US\",\n    \"last_login\": \"2014-11-17T19:02:27.147Z\",\n    \"location\": null,\n    \"meta_description\": null,\n    \"meta_title\": null,\n    \"name\": \"Eric Almeida\",\n    \"slug\": \"eric-almeida\",\n    \"status\":\"active\",\n    \"tour\": null,\n    \"updated_at\":\"2014-10-11T19:02:27.147Z\",\n    \"updated_by\":1,\n    \"uuid\": \"fs4a0021-b22a-33a1-531c-424e2caba3c3\",\n    \"website\": null,\n  }]\n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/users/:id"},"body":"This endpoint allows you to read a specific user based on its id.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/users/:id\\n\\nE.g /users/4\",\n      \"language\": \"http\"\n    },\n    {\n      \"code\": \"$.get(ghost.url.api('users/1')).done(function (data){\\n\\tconsole.log('users', data.users);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"api.users.read({id: 1});\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"{{#get \\\"users\\\" id=\\\"1\\\"}}{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\nYou can [**include**](doc:include) count.posts for this endpoint.","category":"55a92e7ecf45e1390093f32b","createdAt":"2015-11-05T12:52:25.789Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":7,"project":"543023ed7d487022005b3ff8","slug":"usersid","sync_unique":"","title":"/users/:id","type":"get","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

get/users/:id


Query Params

include:
string
count.posts
This endpoint allows you to read a specific user based on its id. [block:code] { "codes": [ { "code": "/users/:id\n\nE.g /users/4", "language": "http" }, { "code": "$.get(ghost.url.api('users/1')).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.users.read({id: 1});", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"users\" id=\"1\"}}{{/get}}", "language": "handlebars" } ] } [/block] You can [**include**](doc:include) count.posts for this endpoint.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



This endpoint allows you to read a specific user based on its id. [block:code] { "codes": [ { "code": "/users/:id\n\nE.g /users/4", "language": "http" }, { "code": "$.get(ghost.url.api('users/1')).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.users.read({id: 1});", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"users\" id=\"1\"}}{{/get}}", "language": "handlebars" } ] } [/block] You can [**include**](doc:include) count.posts for this endpoint.
{"__v":12,"_id":"564202c18c503f17002d695e","api":{"auth":"required","examples":{"codes":[{"name":"jQuery.ajax","code":"$.get(ghost.url.api('users/slug/eric-almeida',)).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});\n        \n// Alternatively you can specify slug as a parameter to the users endpoint\n$.get(ghost.url.api('users', {slug: 'eric-almeida'})).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});","language":"javascript"},{"name":"Internal","code":"api.users.read({slug: \"eric-almeida\"});","language":"javascript"},{"name":"Handlebars","code":"{{#get \"users\" slug=\"eric-almeida\"}}{{/get}}","language":"handlebars"}]},"params":[{"_id":"5659f0934158430d00f05dba","required":false,"desc":"count.posts","default":"","type":"string","name":"include","in":"query"}],"results":{"codes":[{"name":"","code":"{\n  \"users\":[{\n    \"accessibility\": null,\n    \"bio\": null,\n    \"cover\": null,\n    \"created_at\": \"2014-10-11T19:02:27.147Z\",\n    \"created_by\": 1,\n    \"id\":1,\n    \"image\": null,\n    \"language\": \"en_US\",\n    \"last_login\": \"2014-11-17T19:02:27.147Z\",\n    \"location\": null,\n    \"meta_description\": null,\n    \"meta_title\": null,\n    \"name\": \"Eric Almeida\",\n    \"slug\": \"eric-almeida\",\n    \"status\":\"active\",\n    \"tour\": null,\n    \"updated_at\":\"2014-10-11T19:02:27.147Z\",\n    \"updated_by\":1,\n    \"uuid\": \"fs4a0021-b22a-33a1-531c-424e2caba3c3\",\n    \"website\": null,\n  }]\n}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","url":"/users/slug/:slug"},"body":"This endpoint allows you to read a specific user based on its slug.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/users/slug/:slug\\n\\nE.g /users/slug/ericalmeida\",\n      \"language\": \"http\"\n    },\n    {\n      \"code\": \"$.get(ghost.url.api('users/slug/eric-almeida')).done(function (data){\\n\\tconsole.log('users', data.users);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"api.users.read({slug: \\\"eric-almeida\\\"});\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"{{#get \\\"users\\\" slug=\\\"eric-almeida\\\"}}{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\nYou can [**include**](doc:include) count.posts for this endpoint.","category":"55a92e7ecf45e1390093f32b","createdAt":"2015-11-10T14:44:17.117Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":8,"project":"543023ed7d487022005b3ff8","slug":"usersslugslug","sync_unique":"","title":"/users/slug/:slug","type":"get","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

get/users/slug/:slug


Query Params

include:
string
count.posts
This endpoint allows you to read a specific user based on its slug. [block:code] { "codes": [ { "code": "/users/slug/:slug\n\nE.g /users/slug/ericalmeida", "language": "http" }, { "code": "$.get(ghost.url.api('users/slug/eric-almeida')).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.users.read({slug: \"eric-almeida\"});", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"users\" slug=\"eric-almeida\"}}{{/get}}", "language": "handlebars" } ] } [/block] You can [**include**](doc:include) count.posts for this endpoint.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



This endpoint allows you to read a specific user based on its slug. [block:code] { "codes": [ { "code": "/users/slug/:slug\n\nE.g /users/slug/ericalmeida", "language": "http" }, { "code": "$.get(ghost.url.api('users/slug/eric-almeida')).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.users.read({slug: \"eric-almeida\"});", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"users\" slug=\"eric-almeida\"}}{{/get}}", "language": "handlebars" } ] } [/block] You can [**include**](doc:include) count.posts for this endpoint.
{"__v":12,"_id":"5642049e38e37e0d0049feb6","api":{"auth":"required","examples":{"codes":[{"language":"javascript","code":"$.get(ghost.url.api('users', {email: [email protected]'})).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});","name":"jQuery.ajax"},{"language":"javascript","code":"api.users.read({email: \"[email protected]\"});","name":"Internal"},{"language":"handlebars","code":"{{#get \"users\" email=\"[email protected]\"}}{{/get}}","name":"Handlebars"}]},"params":[{"_id":"5659f0b07a23640d00c19d73","required":false,"desc":"count.posts","default":"","type":"string","name":"include","in":"query"}],"results":{"codes":[{"name":"","code":"{\n  \"users\":[{\n    \"accessibility\": null,\n    \"bio\": null,\n    \"cover\": null,\n    \"created_at\": \"2014-10-11T19:02:27.147Z\",\n    \"created_by\": 1,\n    \"id\":1,\n    \"image\": null,\n    \"language\": \"en_US\",\n    \"last_login\": \"2014-11-17T19:02:27.147Z\",\n    \"location\": null,\n    \"meta_description\": null,\n    \"meta_title\": null,\n    \"name\": \"Eric Almeida\",\n    \"slug\": \"eric-almeida\",\n    \"status\":\"active\",\n    \"tour\": null,\n    \"updated_at\":\"2014-10-11T19:02:27.147Z\",\n    \"updated_by\":1,\n    \"uuid\": \"fs4a0021-b22a-33a1-531c-424e2caba3c3\",\n    \"website\": null,\n  }]\n}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","url":"/users/email/:email"},"body":"This endpoint allows you to read a specific user based on its email (Note: email is not returned in the object).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/users/email/:email\\n\\nE.g [email protected]\",\n      \"language\": \"http\"\n    },\n    {\n      \"code\": \"$.get(ghost.url.api([email protected]')).done(function (data){\\n\\tconsole.log('users', data.users);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\\n        \\n// Alternatively you can specify email as a parameter to the users endpoint\\n$.get(ghost.url.api('users', {email: [email protected]'})).done(function (data){\\n\\tconsole.log('users', data.users);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"api.users.read({email: \\\"[email protected]\\\"});\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"{{#get \\\"users\\\" email=\\\"[email protected]\\\"}}{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\nYou can [**include**](doc:include) count.posts for this endpoint.","category":"55a92e7ecf45e1390093f32b","createdAt":"2015-11-10T14:52:14.193Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":9,"project":"543023ed7d487022005b3ff8","slug":"usersemailemail","sync_unique":"","title":"/users/email/:email","type":"get","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

get/users/email/:email


Query Params

include:
string
count.posts
This endpoint allows you to read a specific user based on its email (Note: email is not returned in the object). [block:code] { "codes": [ { "code": "/users/email/:email\n\nE.g [email protected]", "language": "http" }, { "code": "$.get(ghost.url.api([email protected]')).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});\n \n// Alternatively you can specify email as a parameter to the users endpoint\n$.get(ghost.url.api('users', {email: [email protected]'})).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.users.read({email: \"[email protected]\"});", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"users\" email=\"[email protected]\"}}{{/get}}", "language": "handlebars" } ] } [/block] You can [**include**](doc:include) count.posts for this endpoint.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



This endpoint allows you to read a specific user based on its email (Note: email is not returned in the object). [block:code] { "codes": [ { "code": "/users/email/:email\n\nE.g [email protected]", "language": "http" }, { "code": "$.get(ghost.url.api([email protected]')).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});\n \n// Alternatively you can specify email as a parameter to the users endpoint\n$.get(ghost.url.api('users', {email: [email protected]'})).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "api.users.read({email: \"[email protected]\"});", "language": "javascript", "name": "Internal" }, { "code": "{{#get \"users\" email=\"[email protected]\"}}{{/get}}", "language": "handlebars" } ] } [/block] You can [**include**](doc:include) count.posts for this endpoint.
{"__v":13,"_id":"54b457befed7861600c31ef2","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"## Raw post object:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"post: {\\n    id: 1,\\n    uuid: \\\"ec630e45-3342-4d7f-a24c-e448263c975b\\\",\\n    title: \\\"Welcome to Ghost\\\",\\n    slug: \\\"welcome-to-ghost\\\",\\n    markdown: \\\"You're live! Nice.\\\",\\n    html: \\\"<p>You're live! Nice.</p>\\\",\\n    image: '/content/images/2014/12/my-image.png',\\n    featured: false,\\n    page: false,\\n    status: 'published',\\n    language: \\\"en_US\\\",\\n    meta_title: null,\\n    meta_description: null,\\n    author_id: 1,\\n    created_at: \\\"2014-04-15T12:36:28.353Z\\\",\\n    created_by: 1,\\n    updated_at: \\\"2014-04-15T12:36:28.353Z\\\",\\n    updated_by: 1,\\n    published_at: \\\"2014-04-15T12:36:28.363Z\\\",\\n    published_by: 1\\n}\",\n      \"language\": \"json\"\n    },\n    {\n      \"code\": \"post: {\\n    id: 1,\\n    uuid: \\\"ec630e45-3342-4d7f-a24c-e448263c975b\\\",\\n    title: \\\"Welcome to Ghost\\\",\\n    slug: \\\"welcome-to-ghost\\\",\\n    markdown: \\\"You're live! Nice.\\\",\\n    html: \\\"<p>You're live! Nice.</p>\\\",\\n    image: '/content/images/2014/12/my-image.png',\\n    featured: false,\\n    page: false,\\n    status: 'published',\\n    language: \\\"en_US\\\",\\n    meta_title: null,\\n    meta_description: null,\\n    author_id: 1,\\n    created_at: \\\"2014-04-15T12:36:28.353Z\\\",\\n    created_by: 1,\\n    updated_at: \\\"2014-04-15T12:36:28.353Z\\\",\\n    updated_by: 1,\\n    published_at: \\\"2014-04-15T12:36:28.363Z\\\",\\n    published_by: 1,\\n    tags: [{tag}]\\n}\",\n      \"language\": \"text\",\n      \"name\": \"JSON + tags\"\n    },\n    {\n      \"code\": \"post: {\\n    id: 1,\\n    uuid: \\\"ec630e45-3342-4d7f-a24c-e448263c975b\\\",\\n    title: \\\"Welcome to Ghost\\\",\\n    slug: \\\"welcome-to-ghost\\\",\\n    markdown: \\\"You're live! Nice.\\\",\\n    html: \\\"<p>You're live! Nice.</p>\\\",\\n    image: '/content/images/2014/12/my-image.png',\\n    featured: false,\\n    page: false,\\n    status: 'published',\\n    language: \\\"en_US\\\",\\n    meta_title: null,\\n    meta_description: null,\\n    author: {author},\\n    created_at: \\\"2014-04-15T12:36:28.353Z\\\",\\n    created_by: 1,\\n    updated_at: \\\"2014-04-15T12:36:28.353Z\\\",\\n    updated_by: 1,\\n    published_at: \\\"2014-04-15T12:36:28.363Z\\\",\\n    published_by: 1\\n}\",\n      \"language\": \"text\",\n      \"name\": \"JSON + author\"\n    },\n    {\n      \"code\": \"post: {\\n    id: 1,\\n    uuid: \\\"ec630e45-3342-4d7f-a24c-e448263c975b\\\",\\n    title: \\\"Welcome to Ghost\\\",\\n    slug: \\\"welcome-to-ghost\\\",\\n    markdown: \\\"You're live! Nice.\\\",\\n    html: \\\"<p>You're live! Nice.</p>\\\",\\n    image: '/content/images/2014/12/my-image.png',\\n    featured: false,\\n    page: false,\\n    status: 'published',\\n    language: \\\"en_US\\\",\\n    meta_title: null,\\n    meta_description: null,\\n    author: {author},\\n    created_at: \\\"2014-04-15T12:36:28.353Z\\\",\\n    created_by: 1,\\n    updated_at: \\\"2014-04-15T12:36:28.353Z\\\",\\n    updated_by: 1,\\n    published_at: \\\"2014-04-15T12:36:28.363Z\\\",\\n    published_by: 1,\\n    tags: [{tag}]\\n}\",\n      \"language\": \"text\",\n      \"name\": \"JSON + author,tags \"\n    }\n  ]\n}\n[/block]\n## Relations\n\nThe following related objects can be fetched by passing the name as `includes` when making a request:\n\n* **tags** - will include an array of tag objects for each post\n* **author** - will expand the full author object for each post\n\nThe following related objects can be fetched when making a **read** request for a single post only:\n\n* **next_post** - will include the next post, in reverse chronological order\n* **prev_post** - will include the previous post, in reverse chronological order","category":"54b457990512930b00c298be","createdAt":"2015-01-12T23:24:46.290Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"543023ed7d487022005b3ff8","slug":"post","sync_unique":"","title":"Post","type":"basic","updates":[],"user":"542c5cfcddd3190e00228849","version":"543033227d487022005b4032","childrenPages":[]}

Post


## Raw post object: [block:code] { "codes": [ { "code": "post: {\n id: 1,\n uuid: \"ec630e45-3342-4d7f-a24c-e448263c975b\",\n title: \"Welcome to Ghost\",\n slug: \"welcome-to-ghost\",\n markdown: \"You're live! Nice.\",\n html: \"<p>You're live! Nice.</p>\",\n image: '/content/images/2014/12/my-image.png',\n featured: false,\n page: false,\n status: 'published',\n language: \"en_US\",\n meta_title: null,\n meta_description: null,\n author_id: 1,\n created_at: \"2014-04-15T12:36:28.353Z\",\n created_by: 1,\n updated_at: \"2014-04-15T12:36:28.353Z\",\n updated_by: 1,\n published_at: \"2014-04-15T12:36:28.363Z\",\n published_by: 1\n}", "language": "json" }, { "code": "post: {\n id: 1,\n uuid: \"ec630e45-3342-4d7f-a24c-e448263c975b\",\n title: \"Welcome to Ghost\",\n slug: \"welcome-to-ghost\",\n markdown: \"You're live! Nice.\",\n html: \"<p>You're live! Nice.</p>\",\n image: '/content/images/2014/12/my-image.png',\n featured: false,\n page: false,\n status: 'published',\n language: \"en_US\",\n meta_title: null,\n meta_description: null,\n author_id: 1,\n created_at: \"2014-04-15T12:36:28.353Z\",\n created_by: 1,\n updated_at: \"2014-04-15T12:36:28.353Z\",\n updated_by: 1,\n published_at: \"2014-04-15T12:36:28.363Z\",\n published_by: 1,\n tags: [{tag}]\n}", "language": "text", "name": "JSON + tags" }, { "code": "post: {\n id: 1,\n uuid: \"ec630e45-3342-4d7f-a24c-e448263c975b\",\n title: \"Welcome to Ghost\",\n slug: \"welcome-to-ghost\",\n markdown: \"You're live! Nice.\",\n html: \"<p>You're live! Nice.</p>\",\n image: '/content/images/2014/12/my-image.png',\n featured: false,\n page: false,\n status: 'published',\n language: \"en_US\",\n meta_title: null,\n meta_description: null,\n author: {author},\n created_at: \"2014-04-15T12:36:28.353Z\",\n created_by: 1,\n updated_at: \"2014-04-15T12:36:28.353Z\",\n updated_by: 1,\n published_at: \"2014-04-15T12:36:28.363Z\",\n published_by: 1\n}", "language": "text", "name": "JSON + author" }, { "code": "post: {\n id: 1,\n uuid: \"ec630e45-3342-4d7f-a24c-e448263c975b\",\n title: \"Welcome to Ghost\",\n slug: \"welcome-to-ghost\",\n markdown: \"You're live! Nice.\",\n html: \"<p>You're live! Nice.</p>\",\n image: '/content/images/2014/12/my-image.png',\n featured: false,\n page: false,\n status: 'published',\n language: \"en_US\",\n meta_title: null,\n meta_description: null,\n author: {author},\n created_at: \"2014-04-15T12:36:28.353Z\",\n created_by: 1,\n updated_at: \"2014-04-15T12:36:28.353Z\",\n updated_by: 1,\n published_at: \"2014-04-15T12:36:28.363Z\",\n published_by: 1,\n tags: [{tag}]\n}", "language": "text", "name": "JSON + author,tags " } ] } [/block] ## Relations The following related objects can be fetched by passing the name as `includes` when making a request: * **tags** - will include an array of tag objects for each post * **author** - will expand the full author object for each post The following related objects can be fetched when making a **read** request for a single post only: * **next_post** - will include the next post, in reverse chronological order * **prev_post** - will include the previous post, in reverse chronological order
## Raw post object: [block:code] { "codes": [ { "code": "post: {\n id: 1,\n uuid: \"ec630e45-3342-4d7f-a24c-e448263c975b\",\n title: \"Welcome to Ghost\",\n slug: \"welcome-to-ghost\",\n markdown: \"You're live! Nice.\",\n html: \"<p>You're live! Nice.</p>\",\n image: '/content/images/2014/12/my-image.png',\n featured: false,\n page: false,\n status: 'published',\n language: \"en_US\",\n meta_title: null,\n meta_description: null,\n author_id: 1,\n created_at: \"2014-04-15T12:36:28.353Z\",\n created_by: 1,\n updated_at: \"2014-04-15T12:36:28.353Z\",\n updated_by: 1,\n published_at: \"2014-04-15T12:36:28.363Z\",\n published_by: 1\n}", "language": "json" }, { "code": "post: {\n id: 1,\n uuid: \"ec630e45-3342-4d7f-a24c-e448263c975b\",\n title: \"Welcome to Ghost\",\n slug: \"welcome-to-ghost\",\n markdown: \"You're live! Nice.\",\n html: \"<p>You're live! Nice.</p>\",\n image: '/content/images/2014/12/my-image.png',\n featured: false,\n page: false,\n status: 'published',\n language: \"en_US\",\n meta_title: null,\n meta_description: null,\n author_id: 1,\n created_at: \"2014-04-15T12:36:28.353Z\",\n created_by: 1,\n updated_at: \"2014-04-15T12:36:28.353Z\",\n updated_by: 1,\n published_at: \"2014-04-15T12:36:28.363Z\",\n published_by: 1,\n tags: [{tag}]\n}", "language": "text", "name": "JSON + tags" }, { "code": "post: {\n id: 1,\n uuid: \"ec630e45-3342-4d7f-a24c-e448263c975b\",\n title: \"Welcome to Ghost\",\n slug: \"welcome-to-ghost\",\n markdown: \"You're live! Nice.\",\n html: \"<p>You're live! Nice.</p>\",\n image: '/content/images/2014/12/my-image.png',\n featured: false,\n page: false,\n status: 'published',\n language: \"en_US\",\n meta_title: null,\n meta_description: null,\n author: {author},\n created_at: \"2014-04-15T12:36:28.353Z\",\n created_by: 1,\n updated_at: \"2014-04-15T12:36:28.353Z\",\n updated_by: 1,\n published_at: \"2014-04-15T12:36:28.363Z\",\n published_by: 1\n}", "language": "text", "name": "JSON + author" }, { "code": "post: {\n id: 1,\n uuid: \"ec630e45-3342-4d7f-a24c-e448263c975b\",\n title: \"Welcome to Ghost\",\n slug: \"welcome-to-ghost\",\n markdown: \"You're live! Nice.\",\n html: \"<p>You're live! Nice.</p>\",\n image: '/content/images/2014/12/my-image.png',\n featured: false,\n page: false,\n status: 'published',\n language: \"en_US\",\n meta_title: null,\n meta_description: null,\n author: {author},\n created_at: \"2014-04-15T12:36:28.353Z\",\n created_by: 1,\n updated_at: \"2014-04-15T12:36:28.353Z\",\n updated_by: 1,\n published_at: \"2014-04-15T12:36:28.363Z\",\n published_by: 1,\n tags: [{tag}]\n}", "language": "text", "name": "JSON + author,tags " } ] } [/block] ## Relations The following related objects can be fetched by passing the name as `includes` when making a request: * **tags** - will include an array of tag objects for each post * **author** - will expand the full author object for each post The following related objects can be fetched when making a **read** request for a single post only: * **next_post** - will include the next post, in reverse chronological order * **prev_post** - will include the previous post, in reverse chronological order
{"__v":6,"_id":"564316790d9748190079de5e","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"## Raw tag object:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"tag: {\\n    \\\"id\\\":1,\\n    \\\"uuid\\\":\\\"ec3a0924-a59c-45c8-817d-428f6acba7c4\\\",\\n    \\\"name\\\":\\\"Getting Started\\\",\\n    \\\"slug\\\":\\\"getting-started\\\",\\n    \\\"hidden\\\": false,\\n    \\\"parent\\\": null,\\n    \\\"image\\\":null,\\n    \\\"meta_title\\\":null,\\n    \\\"meta_description\\\":null,\\n    \\\"created_at\\\":\\\"2014-11-17T19:02:27.147Z\\\",\\n    \\\"created_by\\\":1,\\n    \\\"updated_at\\\":\\\"2014-11-17T19:02:27.147Z\\\",\\n    \\\"updated_by\\\":1\\n  }\",\n      \"language\": \"json\"\n    },\n    {\n      \"code\": \"tag: {\\n    \\\"id\\\":1,\\n    \\\"uuid\\\":\\\"ec3a0924-a59c-45c8-817d-428f6acba7c4\\\",\\n    \\\"name\\\":\\\"Getting Started\\\",\\n    \\\"slug\\\":\\\"getting-started\\\",\\n    \\\"hidden\\\": false,\\n    \\\"parent\\\": null,\\n    \\\"image\\\":null,\\n    \\\"meta_title\\\":null,\\n    \\\"meta_description\\\":null,\\n    \\\"created_at\\\":\\\"2014-11-17T19:02:27.147Z\\\",\\n    \\\"created_by\\\":1,\\n    \\\"updated_at\\\":\\\"2014-11-17T19:02:27.147Z\\\",\\n    \\\"updated_by\\\":1,\\n    \\\"count\\\": {\\\"posts\\\": 3}\\n  }\",\n      \"language\": \"text\",\n      \"name\": \"JSON + count.posts\"\n    }\n  ]\n}\n[/block]\n## Relations\n\nTags do not currently have any relations that can be included. However, it is possible to optionally include an aggregate post count.\n\n* **count.posts** - how many posts are associated with this tag","category":"54b457990512930b00c298be","createdAt":"2015-11-11T10:20:41.157Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"543023ed7d487022005b3ff8","slug":"tag","sync_unique":"","title":"Tag","type":"basic","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

Tag


## Raw tag object: [block:code] { "codes": [ { "code": "tag: {\n \"id\":1,\n \"uuid\":\"ec3a0924-a59c-45c8-817d-428f6acba7c4\",\n \"name\":\"Getting Started\",\n \"slug\":\"getting-started\",\n \"hidden\": false,\n \"parent\": null,\n \"image\":null,\n \"meta_title\":null,\n \"meta_description\":null,\n \"created_at\":\"2014-11-17T19:02:27.147Z\",\n \"created_by\":1,\n \"updated_at\":\"2014-11-17T19:02:27.147Z\",\n \"updated_by\":1\n }", "language": "json" }, { "code": "tag: {\n \"id\":1,\n \"uuid\":\"ec3a0924-a59c-45c8-817d-428f6acba7c4\",\n \"name\":\"Getting Started\",\n \"slug\":\"getting-started\",\n \"hidden\": false,\n \"parent\": null,\n \"image\":null,\n \"meta_title\":null,\n \"meta_description\":null,\n \"created_at\":\"2014-11-17T19:02:27.147Z\",\n \"created_by\":1,\n \"updated_at\":\"2014-11-17T19:02:27.147Z\",\n \"updated_by\":1,\n \"count\": {\"posts\": 3}\n }", "language": "text", "name": "JSON + count.posts" } ] } [/block] ## Relations Tags do not currently have any relations that can be included. However, it is possible to optionally include an aggregate post count. * **count.posts** - how many posts are associated with this tag
## Raw tag object: [block:code] { "codes": [ { "code": "tag: {\n \"id\":1,\n \"uuid\":\"ec3a0924-a59c-45c8-817d-428f6acba7c4\",\n \"name\":\"Getting Started\",\n \"slug\":\"getting-started\",\n \"hidden\": false,\n \"parent\": null,\n \"image\":null,\n \"meta_title\":null,\n \"meta_description\":null,\n \"created_at\":\"2014-11-17T19:02:27.147Z\",\n \"created_by\":1,\n \"updated_at\":\"2014-11-17T19:02:27.147Z\",\n \"updated_by\":1\n }", "language": "json" }, { "code": "tag: {\n \"id\":1,\n \"uuid\":\"ec3a0924-a59c-45c8-817d-428f6acba7c4\",\n \"name\":\"Getting Started\",\n \"slug\":\"getting-started\",\n \"hidden\": false,\n \"parent\": null,\n \"image\":null,\n \"meta_title\":null,\n \"meta_description\":null,\n \"created_at\":\"2014-11-17T19:02:27.147Z\",\n \"created_by\":1,\n \"updated_at\":\"2014-11-17T19:02:27.147Z\",\n \"updated_by\":1,\n \"count\": {\"posts\": 3}\n }", "language": "text", "name": "JSON + count.posts" } ] } [/block] ## Relations Tags do not currently have any relations that can be included. However, it is possible to optionally include an aggregate post count. * **count.posts** - how many posts are associated with this tag
{"__v":5,"_id":"5643173cab56982100b392aa","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"## Raw user object:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" user: {\\n    \\\"accessibility\\\": null,\\n    \\\"bio\\\": null,\\n    \\\"cover\\\": null,\\n    \\\"created_at\\\": \\\"2014-10-11T19:02:27.147Z\\\",\\n    \\\"created_by\\\": 1,\\n    \\\"id\\\":1,\\n    \\\"image\\\": null,\\n    \\\"language\\\": \\\"en_US\\\",\\n    \\\"last_login\\\": \\\"2014-11-17T19:02:27.147Z\\\",\\n    \\\"location\\\": null,\\n    \\\"meta_description\\\": null,\\n    \\\"meta_title\\\": null,\\n    \\\"name\\\": \\\"Eric Almeida\\\",\\n    \\\"slug\\\": \\\"eric-almeida\\\",\\n    \\\"status\\\":\\\"active\\\",\\n    \\\"tour\\\": null,\\n    \\\"updated_at\\\":\\\"2014-10-11T19:02:27.147Z\\\",\\n    \\\"updated_by\\\":1,\\n    \\\"uuid\\\": \\\"fs4a0021-b22a-33a1-531c-424e2caba3c3\\\",\\n    \\\"website\\\": null\\n }\",\n      \"language\": \"json\"\n    },\n    {\n      \"code\": \" user: {\\n    \\\"accessibility\\\": null,\\n    \\\"bio\\\": null,\\n    \\\"cover\\\": null,\\n    \\\"created_at\\\": \\\"2014-10-11T19:02:27.147Z\\\",\\n    \\\"created_by\\\": 1,\\n    \\\"id\\\":1,\\n    \\\"image\\\": null,\\n    \\\"language\\\": \\\"en_US\\\",\\n    \\\"last_login\\\": \\\"2014-11-17T19:02:27.147Z\\\",\\n    \\\"location\\\": null,\\n    \\\"meta_description\\\": null,\\n    \\\"meta_title\\\": null,\\n    \\\"name\\\": \\\"Eric Almeida\\\",\\n    \\\"slug\\\": \\\"eric-almeida\\\",\\n    \\\"status\\\":\\\"active\\\",\\n    \\\"tour\\\": null,\\n    \\\"updated_at\\\":\\\"2014-10-11T19:02:27.147Z\\\",\\n    \\\"updated_by\\\":1,\\n    \\\"uuid\\\": \\\"fs4a0021-b22a-33a1-531c-424e2caba3c3\\\",\\n    \\\"website\\\": null,\\n    \\\"count\\\": {\\\"posts\\\": 3}\\n }\",\n      \"language\": \"text\",\n      \"name\": \"JSON + count.posts\"\n    }\n  ]\n}\n[/block]\n## Relations\n\nUsers do not currently have any relations that can be included. However, it is possible to optionally include an aggregate post count.\n\n* **count.posts** - how many posts were authored by this user","category":"54b457990512930b00c298be","createdAt":"2015-11-11T10:23:56.431Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"543023ed7d487022005b3ff8","slug":"user","sync_unique":"","title":"User","type":"basic","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

User


## Raw user object: [block:code] { "codes": [ { "code": " user: {\n \"accessibility\": null,\n \"bio\": null,\n \"cover\": null,\n \"created_at\": \"2014-10-11T19:02:27.147Z\",\n \"created_by\": 1,\n \"id\":1,\n \"image\": null,\n \"language\": \"en_US\",\n \"last_login\": \"2014-11-17T19:02:27.147Z\",\n \"location\": null,\n \"meta_description\": null,\n \"meta_title\": null,\n \"name\": \"Eric Almeida\",\n \"slug\": \"eric-almeida\",\n \"status\":\"active\",\n \"tour\": null,\n \"updated_at\":\"2014-10-11T19:02:27.147Z\",\n \"updated_by\":1,\n \"uuid\": \"fs4a0021-b22a-33a1-531c-424e2caba3c3\",\n \"website\": null\n }", "language": "json" }, { "code": " user: {\n \"accessibility\": null,\n \"bio\": null,\n \"cover\": null,\n \"created_at\": \"2014-10-11T19:02:27.147Z\",\n \"created_by\": 1,\n \"id\":1,\n \"image\": null,\n \"language\": \"en_US\",\n \"last_login\": \"2014-11-17T19:02:27.147Z\",\n \"location\": null,\n \"meta_description\": null,\n \"meta_title\": null,\n \"name\": \"Eric Almeida\",\n \"slug\": \"eric-almeida\",\n \"status\":\"active\",\n \"tour\": null,\n \"updated_at\":\"2014-10-11T19:02:27.147Z\",\n \"updated_by\":1,\n \"uuid\": \"fs4a0021-b22a-33a1-531c-424e2caba3c3\",\n \"website\": null,\n \"count\": {\"posts\": 3}\n }", "language": "text", "name": "JSON + count.posts" } ] } [/block] ## Relations Users do not currently have any relations that can be included. However, it is possible to optionally include an aggregate post count. * **count.posts** - how many posts were authored by this user
## Raw user object: [block:code] { "codes": [ { "code": " user: {\n \"accessibility\": null,\n \"bio\": null,\n \"cover\": null,\n \"created_at\": \"2014-10-11T19:02:27.147Z\",\n \"created_by\": 1,\n \"id\":1,\n \"image\": null,\n \"language\": \"en_US\",\n \"last_login\": \"2014-11-17T19:02:27.147Z\",\n \"location\": null,\n \"meta_description\": null,\n \"meta_title\": null,\n \"name\": \"Eric Almeida\",\n \"slug\": \"eric-almeida\",\n \"status\":\"active\",\n \"tour\": null,\n \"updated_at\":\"2014-10-11T19:02:27.147Z\",\n \"updated_by\":1,\n \"uuid\": \"fs4a0021-b22a-33a1-531c-424e2caba3c3\",\n \"website\": null\n }", "language": "json" }, { "code": " user: {\n \"accessibility\": null,\n \"bio\": null,\n \"cover\": null,\n \"created_at\": \"2014-10-11T19:02:27.147Z\",\n \"created_by\": 1,\n \"id\":1,\n \"image\": null,\n \"language\": \"en_US\",\n \"last_login\": \"2014-11-17T19:02:27.147Z\",\n \"location\": null,\n \"meta_description\": null,\n \"meta_title\": null,\n \"name\": \"Eric Almeida\",\n \"slug\": \"eric-almeida\",\n \"status\":\"active\",\n \"tour\": null,\n \"updated_at\":\"2014-10-11T19:02:27.147Z\",\n \"updated_by\":1,\n \"uuid\": \"fs4a0021-b22a-33a1-531c-424e2caba3c3\",\n \"website\": null,\n \"count\": {\"posts\": 3}\n }", "language": "text", "name": "JSON + count.posts" } ] } [/block] ## Relations Users do not currently have any relations that can be included. However, it is possible to optionally include an aggregate post count. * **count.posts** - how many posts were authored by this user
{"__v":32,"_id":"56587058c4744f0d008a260f","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"The **limit** parameter allows you to change the number of items returned per [**page**](doc:page) of your [**paginated**](doc:pagination) collection when making browse requests.\n\n- **Allowed values:** a positive integer, or **all**\n- **Default value:** 15\n\n**Note:** Requesting either a large number, or **all** items could put significant load on a blog, and may also exceed maximum request sizes\\*. Therefore if you do need to use 'all' it is recommended that you combine this by using the [Fields](doc:fields) param to restrict the data returned to only what is needed.\n\n\nExamples:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Fetch the 20 most recently published posts\\n$.get(ghost.url.api('posts', {limit: 20})).done(function (data){\\n\\tconsole.log('posts', data.posts);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\\n\\n// Fetch all tags\\n$.get(ghost.url.api('tags', {limit: \\\"all\\\"})).done(function (data){\\n\\tconsole.log('tags', data.tags);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"// Fetch the 20 most recently published posts\\napi.posts.browse({limit: 20});\\n\\n// Fetch all tags\\napi.tags.browse({limit: all});\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"// Fetch the 20 most recently published posts\\n{{#get \\\"posts\\\" limit=\\\"20\\\"}}{{/get}}\\n\\n// Fetch all tags\\n{{#get \\\"tags\\\" limit=\\\"all\\\"}}{{/get}}\",\n      \"language\": \"handlebars\",\n      \"name\": \"Handlebars\"\n    }\n  ]\n}\n[/block]\n\\* Maximum request sizes can be limited by the browser, server, or a step in between and are therefore unpredictable.","category":"565a80a2d0c3da0d0036f268","createdAt":"2015-11-27T15:01:44.884Z","excerpt":"API parameter","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"543023ed7d487022005b3ff8","slug":"limit","sync_unique":"","title":"Limit","type":"basic","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

Limit

API parameter

The **limit** parameter allows you to change the number of items returned per [**page**](doc:page) of your [**paginated**](doc:pagination) collection when making browse requests. - **Allowed values:** a positive integer, or **all** - **Default value:** 15 **Note:** Requesting either a large number, or **all** items could put significant load on a blog, and may also exceed maximum request sizes\*. Therefore if you do need to use 'all' it is recommended that you combine this by using the [Fields](doc:fields) param to restrict the data returned to only what is needed. Examples: [block:code] { "codes": [ { "code": "// Fetch the 20 most recently published posts\n$.get(ghost.url.api('posts', {limit: 20})).done(function (data){\n\tconsole.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});\n\n// Fetch all tags\n$.get(ghost.url.api('tags', {limit: \"all\"})).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "// Fetch the 20 most recently published posts\napi.posts.browse({limit: 20});\n\n// Fetch all tags\napi.tags.browse({limit: all});", "language": "javascript", "name": "Internal" }, { "code": "// Fetch the 20 most recently published posts\n{{#get \"posts\" limit=\"20\"}}{{/get}}\n\n// Fetch all tags\n{{#get \"tags\" limit=\"all\"}}{{/get}}", "language": "handlebars", "name": "Handlebars" } ] } [/block] \* Maximum request sizes can be limited by the browser, server, or a step in between and are therefore unpredictable.
The **limit** parameter allows you to change the number of items returned per [**page**](doc:page) of your [**paginated**](doc:pagination) collection when making browse requests. - **Allowed values:** a positive integer, or **all** - **Default value:** 15 **Note:** Requesting either a large number, or **all** items could put significant load on a blog, and may also exceed maximum request sizes\*. Therefore if you do need to use 'all' it is recommended that you combine this by using the [Fields](doc:fields) param to restrict the data returned to only what is needed. Examples: [block:code] { "codes": [ { "code": "// Fetch the 20 most recently published posts\n$.get(ghost.url.api('posts', {limit: 20})).done(function (data){\n\tconsole.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});\n\n// Fetch all tags\n$.get(ghost.url.api('tags', {limit: \"all\"})).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "// Fetch the 20 most recently published posts\napi.posts.browse({limit: 20});\n\n// Fetch all tags\napi.tags.browse({limit: all});", "language": "javascript", "name": "Internal" }, { "code": "// Fetch the 20 most recently published posts\n{{#get \"posts\" limit=\"20\"}}{{/get}}\n\n// Fetch all tags\n{{#get \"tags\" limit=\"all\"}}{{/get}}", "language": "handlebars", "name": "Handlebars" } ] } [/block] \* Maximum request sizes can be limited by the browser, server, or a step in between and are therefore unpredictable.
{"__v":11,"_id":"565880a63df5130d00a57a25","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"The page parameter allows you to specify which page of a [**paginated**](doc:pagination) collection to return.\n\nWhen making an API Browse request, the response will be a paginated collection.\n\nThis means if you make a request with a [**limit**](doc:limit) of 5 on a collection of 15, page 1 will result in the first five items of your collection. Page 2 will return items 6- 10 etc.\n\nIf **page** is not specified, the default value will be used.\n\n**Default value: 1** \n\nExample:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Fetch the 4th page of posts\\n$.get(ghost.url.api('posts', {page: 2})).done(function (data){\\n\\tconsole.log('posts', data.posts);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"// Fetch the 4th page of posts\\napi.posts.browse({page: 4});\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"// Fetch the 4th page of posts\\n{{#get \\\"posts\\\" page=\\\"4\\\"}}{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]","category":"565a80a2d0c3da0d0036f268","createdAt":"2015-11-27T16:11:18.816Z","excerpt":"API Parameter","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"543023ed7d487022005b3ff8","slug":"page","sync_unique":"","title":"Page","type":"basic","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

Page

API Parameter

The page parameter allows you to specify which page of a [**paginated**](doc:pagination) collection to return. When making an API Browse request, the response will be a paginated collection. This means if you make a request with a [**limit**](doc:limit) of 5 on a collection of 15, page 1 will result in the first five items of your collection. Page 2 will return items 6- 10 etc. If **page** is not specified, the default value will be used. **Default value: 1** Example: [block:code] { "codes": [ { "code": "// Fetch the 4th page of posts\n$.get(ghost.url.api('posts', {page: 2})).done(function (data){\n\tconsole.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "// Fetch the 4th page of posts\napi.posts.browse({page: 4});", "language": "javascript", "name": "Internal" }, { "code": "// Fetch the 4th page of posts\n{{#get \"posts\" page=\"4\"}}{{/get}}", "language": "handlebars" } ] } [/block]
The page parameter allows you to specify which page of a [**paginated**](doc:pagination) collection to return. When making an API Browse request, the response will be a paginated collection. This means if you make a request with a [**limit**](doc:limit) of 5 on a collection of 15, page 1 will result in the first five items of your collection. Page 2 will return items 6- 10 etc. If **page** is not specified, the default value will be used. **Default value: 1** Example: [block:code] { "codes": [ { "code": "// Fetch the 4th page of posts\n$.get(ghost.url.api('posts', {page: 2})).done(function (data){\n\tconsole.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "// Fetch the 4th page of posts\napi.posts.browse({page: 4});", "language": "javascript", "name": "Internal" }, { "code": "// Fetch the 4th page of posts\n{{#get \"posts\" page=\"4\"}}{{/get}}", "language": "handlebars" } ] } [/block]
{"__v":13,"_id":"565881a31d3c450d0019dbcb","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"The **order** parameter allows you to specify how your data is ordered before being returned.\n\nYou can choose any valid resource *field* in ascending (`asc`) or descending (`desc`) order.\n\n**Default** values vary depending on the Resource:\n[**Post**](doc:post): *\"published_at desc\"*\n[**Tag**](doc:tag): *\"id desc\"*\n[**User**](doc:user): *\"last_login desc\"*\n\nExample:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Fetch tags in alphabetical order of name ([0-9], A->Z)\\n$.get(ghost.url.api('tags', {order: \\\"name asc\\\"})).done(function (data){\\n\\tconsole.log('tags', data.tags);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"// Fetch tags in alphabetical order of name ([0-9], A->Z)\\napi.tags.browse({order: \\\"name asc\\\"});\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"// Fetch tags in alphabetical order of name ([0-9], A->Z)\\n{{#get \\\"tags\\\" order=\\\"name asc\\\"}}{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]","category":"565a80a2d0c3da0d0036f268","createdAt":"2015-11-27T16:15:31.274Z","excerpt":"API parameter","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"543023ed7d487022005b3ff8","slug":"order","sync_unique":"","title":"Order","type":"basic","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

Order

API parameter

The **order** parameter allows you to specify how your data is ordered before being returned. You can choose any valid resource *field* in ascending (`asc`) or descending (`desc`) order. **Default** values vary depending on the Resource: [**Post**](doc:post): *"published_at desc"* [**Tag**](doc:tag): *"id desc"* [**User**](doc:user): *"last_login desc"* Example: [block:code] { "codes": [ { "code": "// Fetch tags in alphabetical order of name ([0-9], A->Z)\n$.get(ghost.url.api('tags', {order: \"name asc\"})).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "// Fetch tags in alphabetical order of name ([0-9], A->Z)\napi.tags.browse({order: \"name asc\"});", "language": "javascript", "name": "Internal" }, { "code": "// Fetch tags in alphabetical order of name ([0-9], A->Z)\n{{#get \"tags\" order=\"name asc\"}}{{/get}}", "language": "handlebars" } ] } [/block]
The **order** parameter allows you to specify how your data is ordered before being returned. You can choose any valid resource *field* in ascending (`asc`) or descending (`desc`) order. **Default** values vary depending on the Resource: [**Post**](doc:post): *"published_at desc"* [**Tag**](doc:tag): *"id desc"* [**User**](doc:user): *"last_login desc"* Example: [block:code] { "codes": [ { "code": "// Fetch tags in alphabetical order of name ([0-9], A->Z)\n$.get(ghost.url.api('tags', {order: \"name asc\"})).done(function (data){\n\tconsole.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "// Fetch tags in alphabetical order of name ([0-9], A->Z)\napi.tags.browse({order: \"name asc\"});", "language": "javascript", "name": "Internal" }, { "code": "// Fetch tags in alphabetical order of name ([0-9], A->Z)\n{{#get \"tags\" order=\"name asc\"}}{{/get}}", "language": "handlebars" } ] } [/block]
{"__v":20,"_id":"55a93374c8bd450d000dd1d9","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"When making an API request, the resulting response will only contain base data from the Resource itself.\n\nA Resource may have additional related data that can be included to expand your collection.\n\nBase Resource data:\n* [**Post**](doc:post)\n* [**Tag**](doc:tag)\n* [**User**](doc:user)\n\nThere can be multiple *includes* separated by a comma.\n\n### **Post Resource**\n\nThe post resource by default has a tags array and an author_id. These can be expanded to include more information.\n\nInclude options: \"author\" - expands author, \"tags\" - expands tags.\n\nExample:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Fetch posts with author and tags\\n$.get(ghost.url.api('posts', {include=\\\"author,tags\\\"})).done(function (data){\\n\\tconole.log('posts', data.posts);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"// Fetch posts with author and tags\\napi.posts.browse({include: \\\"author,tags\\\"});\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"// Fetch posts with author and tags\\n{{#get \\\"posts\\\" include=\\\"author,tags\\\"}}{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\n### **User & Tag Resources**\n\nThe User and Tag resource can be expanded to include the post count for each resource.\n\nInclude option: \"count.posts\"  \n\nNote: If you include count.posts you can use it to [**order**](doc:order) your collection.\n\nExample:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Fetch tags with post count\\n$.get(ghost.url.api('tags', {include=\\\"count.posts\\\"})).done(function (data){\\n  console.log('tags', data.tags);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\\n        \\n// Fetch users and order by post count\\n$.get(ghost.url.api('users', {include=\\\"count.posts\\\", order=\\\"count.posts desc\\\"})).done(function (data){\\n  console.log('users', data.users);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"// Fetch tags with post count\\napi.tags.browse({include: \\\"count.posts\\\"});\\n\\n// Fetch users and order by post count\\napi.users.browse({include: \\\"count.posts\\\", order: \\\"count.posts desc\\\"});\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"// Fetch tags with post count\\n{{#get \\\"tags\\\" include=\\\"count.posts\\\"}}\\n    {{#foreach tags}}\\n        <p>post count: {{count.posts}}</p>\\n    {{/foreach}}\\n{{/get}}\\n\\n// Fetch users and order by post count\\n{{#get \\\"users\\\" include=\\\"count.posts\\\" order=\\\"count.posts desc\\\"}}\\n    {{#foreach users}}\\n        <p>post count: {{count.posts}}</p>\\n    {{/foreach}}\\n{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]","category":"565a80a2d0c3da0d0036f268","createdAt":"2015-07-17T16:55:16.749Z","excerpt":"API Parameter","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"project":"543023ed7d487022005b3ff8","slug":"includes","sync_unique":"","title":"Include","type":"basic","updates":[],"user":"542c5cfcddd3190e00228849","version":"543033227d487022005b4032","childrenPages":[]}

Include

API Parameter

When making an API request, the resulting response will only contain base data from the Resource itself. A Resource may have additional related data that can be included to expand your collection. Base Resource data: * [**Post**](doc:post) * [**Tag**](doc:tag) * [**User**](doc:user) There can be multiple *includes* separated by a comma. ### **Post Resource** The post resource by default has a tags array and an author_id. These can be expanded to include more information. Include options: "author" - expands author, "tags" - expands tags. Example: [block:code] { "codes": [ { "code": "// Fetch posts with author and tags\n$.get(ghost.url.api('posts', {include=\"author,tags\"})).done(function (data){\n\tconole.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "// Fetch posts with author and tags\napi.posts.browse({include: \"author,tags\"});", "language": "javascript", "name": "Internal" }, { "code": "// Fetch posts with author and tags\n{{#get \"posts\" include=\"author,tags\"}}{{/get}}", "language": "handlebars" } ] } [/block] ### **User & Tag Resources** The User and Tag resource can be expanded to include the post count for each resource. Include option: "count.posts" Note: If you include count.posts you can use it to [**order**](doc:order) your collection. Example: [block:code] { "codes": [ { "code": "// Fetch tags with post count\n$.get(ghost.url.api('tags', {include=\"count.posts\"})).done(function (data){\n console.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});\n \n// Fetch users and order by post count\n$.get(ghost.url.api('users', {include=\"count.posts\", order=\"count.posts desc\"})).done(function (data){\n console.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "// Fetch tags with post count\napi.tags.browse({include: \"count.posts\"});\n\n// Fetch users and order by post count\napi.users.browse({include: \"count.posts\", order: \"count.posts desc\"});", "language": "javascript", "name": "Internal" }, { "code": "// Fetch tags with post count\n{{#get \"tags\" include=\"count.posts\"}}\n {{#foreach tags}}\n <p>post count: {{count.posts}}</p>\n {{/foreach}}\n{{/get}}\n\n// Fetch users and order by post count\n{{#get \"users\" include=\"count.posts\" order=\"count.posts desc\"}}\n {{#foreach users}}\n <p>post count: {{count.posts}}</p>\n {{/foreach}}\n{{/get}}", "language": "handlebars" } ] } [/block]
When making an API request, the resulting response will only contain base data from the Resource itself. A Resource may have additional related data that can be included to expand your collection. Base Resource data: * [**Post**](doc:post) * [**Tag**](doc:tag) * [**User**](doc:user) There can be multiple *includes* separated by a comma. ### **Post Resource** The post resource by default has a tags array and an author_id. These can be expanded to include more information. Include options: "author" - expands author, "tags" - expands tags. Example: [block:code] { "codes": [ { "code": "// Fetch posts with author and tags\n$.get(ghost.url.api('posts', {include=\"author,tags\"})).done(function (data){\n\tconole.log('posts', data.posts);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "// Fetch posts with author and tags\napi.posts.browse({include: \"author,tags\"});", "language": "javascript", "name": "Internal" }, { "code": "// Fetch posts with author and tags\n{{#get \"posts\" include=\"author,tags\"}}{{/get}}", "language": "handlebars" } ] } [/block] ### **User & Tag Resources** The User and Tag resource can be expanded to include the post count for each resource. Include option: "count.posts" Note: If you include count.posts you can use it to [**order**](doc:order) your collection. Example: [block:code] { "codes": [ { "code": "// Fetch tags with post count\n$.get(ghost.url.api('tags', {include=\"count.posts\"})).done(function (data){\n console.log('tags', data.tags);\n}).fail(function (err){\n\tconsole.log(err);\n});\n \n// Fetch users and order by post count\n$.get(ghost.url.api('users', {include=\"count.posts\", order=\"count.posts desc\"})).done(function (data){\n console.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "// Fetch tags with post count\napi.tags.browse({include: \"count.posts\"});\n\n// Fetch users and order by post count\napi.users.browse({include: \"count.posts\", order: \"count.posts desc\"});", "language": "javascript", "name": "Internal" }, { "code": "// Fetch tags with post count\n{{#get \"tags\" include=\"count.posts\"}}\n {{#foreach tags}}\n <p>post count: {{count.posts}}</p>\n {{/foreach}}\n{{/get}}\n\n// Fetch users and order by post count\n{{#get \"users\" include=\"count.posts\" order=\"count.posts desc\"}}\n {{#foreach users}}\n <p>post count: {{count.posts}}</p>\n {{/foreach}}\n{{/get}}", "language": "handlebars" } ] } [/block]
{"__v":8,"_id":"5658c0e7592da30d0092dc16","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"Allows you to specify which resource **fields** to retrieve rather than retrieving the. whole object.\n\nExample:\n\nIf you make a `{{get}}` request for the *Post* resource you may only want the *title* so you could specify *title* as a field. This would reduce the network overhead as you are no longer receiving the html and markdown etc.\n\nYou can choose multiple **fields** with a comma separating the string.\n\nExample:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Fetch only the bio and name for users\\n$.get(ghost.url.api('users', {fields: \\\"bio,name\\\"})).done(function (data){\\n\\tconsole.log('users', data.users);\\n}).fail(function (err){\\n\\tconsole.log(err);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery.ajax\"\n    },\n    {\n      \"code\": \"// Fetch only the bio and name for users\\napi.users.browse({fields: \\\"bio,name\\\"});\",\n      \"language\": \"javascript\",\n      \"name\": \"Internal\"\n    },\n    {\n      \"code\": \"// Fetch only the bio and name for users\\n{{#get \\\"users\\\" fields=\\\"bio, name\\\"}}\\n    {{#foreach user}}\\n        <p>{{bio}}</p>\\n    {{/foreach}}\\n{{/get}}\",\n      \"language\": \"handlebars\"\n    }\n  ]\n}\n[/block]\nSummary of valid **fields** for each Resource:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Resource\",\n    \"h-1\": \"Fields\",\n    \"0-0\": \"Post\",\n    \"1-0\": \"User\",\n    \"2-0\": \"Tag\",\n    \"0-1\": \"id, uuid, title, slug, markdown, html, image, featured, page, status, language, created_at, created_by, updated_at, updated_by, published_at, published_by\",\n    \"1-1\": \"id, uuid, name, slug, image, cover, bio, website, location, status, language, last_login, created_at, created_by, updated_at, updated_by\",\n    \"2-1\": \"id, uuid, name, slug, description, image, created_at, created_by, updated_at, updated_by\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]","category":"565a80a2d0c3da0d0036f268","createdAt":"2015-11-27T20:45:27.477Z","excerpt":"API parameter","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"project":"543023ed7d487022005b3ff8","slug":"fields","sync_unique":"","title":"Fields","type":"basic","updates":[],"user":"55acc88c6b4ff90d00784b61","version":"543033227d487022005b4032","childrenPages":[]}

Fields

API parameter

Allows you to specify which resource **fields** to retrieve rather than retrieving the. whole object. Example: If you make a `{{get}}` request for the *Post* resource you may only want the *title* so you could specify *title* as a field. This would reduce the network overhead as you are no longer receiving the html and markdown etc. You can choose multiple **fields** with a comma separating the string. Example: [block:code] { "codes": [ { "code": "// Fetch only the bio and name for users\n$.get(ghost.url.api('users', {fields: \"bio,name\"})).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "// Fetch only the bio and name for users\napi.users.browse({fields: \"bio,name\"});", "language": "javascript", "name": "Internal" }, { "code": "// Fetch only the bio and name for users\n{{#get \"users\" fields=\"bio, name\"}}\n {{#foreach user}}\n <p>{{bio}}</p>\n {{/foreach}}\n{{/get}}", "language": "handlebars" } ] } [/block] Summary of valid **fields** for each Resource: [block:parameters] { "data": { "h-0": "Resource", "h-1": "Fields", "0-0": "Post", "1-0": "User", "2-0": "Tag", "0-1": "id, uuid, title, slug, markdown, html, image, featured, page, status, language, created_at, created_by, updated_at, updated_by, published_at, published_by", "1-1": "id, uuid, name, slug, image, cover, bio, website, location, status, language, last_login, created_at, created_by, updated_at, updated_by", "2-1": "id, uuid, name, slug, description, image, created_at, created_by, updated_at, updated_by" }, "cols": 2, "rows": 3 } [/block]
Allows you to specify which resource **fields** to retrieve rather than retrieving the. whole object. Example: If you make a `{{get}}` request for the *Post* resource you may only want the *title* so you could specify *title* as a field. This would reduce the network overhead as you are no longer receiving the html and markdown etc. You can choose multiple **fields** with a comma separating the string. Example: [block:code] { "codes": [ { "code": "// Fetch only the bio and name for users\n$.get(ghost.url.api('users', {fields: \"bio,name\"})).done(function (data){\n\tconsole.log('users', data.users);\n}).fail(function (err){\n\tconsole.log(err);\n});", "language": "javascript", "name": "jQuery.ajax" }, { "code": "// Fetch only the bio and name for users\napi.users.browse({fields: \"bio,name\"});", "language": "javascript", "name": "Internal" }, { "code": "// Fetch only the bio and name for users\n{{#get \"users\" fields=\"bio, name\"}}\n {{#foreach user}}\n <p>{{bio}}</p>\n {{/foreach}}\n{{/get}}", "language": "handlebars" } ] } [/block] Summary of valid **fields** for each Resource: [block:parameters] { "data": { "h-0": "Resource", "h-1": "Fields", "0-0": "Post", "1-0": "User", "2-0": "Tag", "0-1": "id, uuid, title, slug, markdown, html, image, featured, page, status, language, created_at, created_by, updated_at, updated_by, published_at, published_by", "1-1": "id, uuid, name, slug, image, cover, bio, website, location, status, language, last_login, created_at, created_by, updated_at, updated_by", "2-1": "id, uuid, name, slug, description, image, created_at, created_by, updated_at, updated_by" }, "cols": 2, "rows": 3 } [/block]
{"__v":24,"_id":"55a9337bcf45e1390093f35e","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"The `filter` parameter allows for filtering the results returned from the various endpoints in various ways. For example fetching only posts marked as featured by adding `filter=featured:true` to your query.\n\nFiltering in Ghost looks a bit like filtering you may have seen before in Gmail or on GitHub.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Getting started with filters\"\n}\n[/block]\nFilters are made up of rules, with a **property**, a **value** and an **operator**.  Where **property** is the field you want to filter against, e.g. `featured`, **value** is what you want to match e.g. `true` and **operator** is most commonly 'equals' e.g. `:`.\n\nWhen specifying a filter, the **property** and **value** are always separated by a colon `:`. If no other operator is provided, then this is a simple 'equals' comparison.\n\n`featured:true` - return all posts where the featured property is equal to true.\n\nYou can also do a 'not equals' query, by adding the 'not' operator `-` after the colon. For example, if you wanted to find all posts which have an image, you could look for all posts where image is not null: `images:-null`.\n\nThe full list of operators is shown below.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Filters with multiple rules\"\n}\n[/block]\nYou can combine rules using either 'and' or 'or'. If you'd like to find all posts that are either featured, or they have an image, then you can combine these two rules with a comma `,` which represents 'or': `filter=\"featured:true,image:-null\"`.\n\nIf you're looking for all published posts which are not static pages, then you can combine the two rules with a plus `+` which represents and: `filter=status:published+page:true`. This is the default query performed by the posts endpoint.\n\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Syntax Reference\"\n}\n[/block]\n### Operators\n\n* `-` - not operator\n* `>` - greater than operator\n* `>=` - greater than or equals operator\n* `<` - less than operator\n* `<=` - less than or equals operator\n\n### Combinations\n\n* `+` - represents and\n* `,` - represents or\n* `(` filter expression `)` - overrides operator precedence","category":"565a80a2d0c3da0d0036f268","createdAt":"2015-07-17T16:55:23.946Z","excerpt":"Filtering API responses to retrieve specific data","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":5,"project":"543023ed7d487022005b3ff8","slug":"filter","sync_unique":"","title":"Filter","type":"basic","updates":[],"user":"542c5cfcddd3190e00228849","version":"543033227d487022005b4032","childrenPages":[]}

Filter

Filtering API responses to retrieve specific data

The `filter` parameter allows for filtering the results returned from the various endpoints in various ways. For example fetching only posts marked as featured by adding `filter=featured:true` to your query. Filtering in Ghost looks a bit like filtering you may have seen before in Gmail or on GitHub. [block:api-header] { "type": "basic", "title": "Getting started with filters" } [/block] Filters are made up of rules, with a **property**, a **value** and an **operator**. Where **property** is the field you want to filter against, e.g. `featured`, **value** is what you want to match e.g. `true` and **operator** is most commonly 'equals' e.g. `:`. When specifying a filter, the **property** and **value** are always separated by a colon `:`. If no other operator is provided, then this is a simple 'equals' comparison. `featured:true` - return all posts where the featured property is equal to true. You can also do a 'not equals' query, by adding the 'not' operator `-` after the colon. For example, if you wanted to find all posts which have an image, you could look for all posts where image is not null: `images:-null`. The full list of operators is shown below. [block:api-header] { "type": "basic", "title": "Filters with multiple rules" } [/block] You can combine rules using either 'and' or 'or'. If you'd like to find all posts that are either featured, or they have an image, then you can combine these two rules with a comma `,` which represents 'or': `filter="featured:true,image:-null"`. If you're looking for all published posts which are not static pages, then you can combine the two rules with a plus `+` which represents and: `filter=status:published+page:true`. This is the default query performed by the posts endpoint. [block:api-header] { "type": "basic", "title": "Syntax Reference" } [/block] ### Operators * `-` - not operator * `>` - greater than operator * `>=` - greater than or equals operator * `<` - less than operator * `<=` - less than or equals operator ### Combinations * `+` - represents and * `,` - represents or * `(` filter expression `)` - overrides operator precedence
The `filter` parameter allows for filtering the results returned from the various endpoints in various ways. For example fetching only posts marked as featured by adding `filter=featured:true` to your query. Filtering in Ghost looks a bit like filtering you may have seen before in Gmail or on GitHub. [block:api-header] { "type": "basic", "title": "Getting started with filters" } [/block] Filters are made up of rules, with a **property**, a **value** and an **operator**. Where **property** is the field you want to filter against, e.g. `featured`, **value** is what you want to match e.g. `true` and **operator** is most commonly 'equals' e.g. `:`. When specifying a filter, the **property** and **value** are always separated by a colon `:`. If no other operator is provided, then this is a simple 'equals' comparison. `featured:true` - return all posts where the featured property is equal to true. You can also do a 'not equals' query, by adding the 'not' operator `-` after the colon. For example, if you wanted to find all posts which have an image, you could look for all posts where image is not null: `images:-null`. The full list of operators is shown below. [block:api-header] { "type": "basic", "title": "Filters with multiple rules" } [/block] You can combine rules using either 'and' or 'or'. If you'd like to find all posts that are either featured, or they have an image, then you can combine these two rules with a comma `,` which represents 'or': `filter="featured:true,image:-null"`. If you're looking for all published posts which are not static pages, then you can combine the two rules with a plus `+` which represents and: `filter=status:published+page:true`. This is the default query performed by the posts endpoint. [block:api-header] { "type": "basic", "title": "Syntax Reference" } [/block] ### Operators * `-` - not operator * `>` - greater than operator * `>=` - greater than or equals operator * `<` - less than operator * `<=` - less than or equals operator ### Combinations * `+` - represents and * `,` - represents or * `(` filter expression `)` - overrides operator precedence
{"__v":42,"_id":"566d68f812ceed1700400b33","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"This recipe is for you, if you have a blog located on a subdomain or subdirectory of your site and want to pull data into a different site. E.g. Your blog lives at blog.mysite.com and you want to list out the 3 most recent blog posts on mysite.com.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Beta Feature\",\n  \"body\": \"This recipe uses the Ghost Public API, which is currently a Beta feature and should be not be used in production. For more information on what Beta means, see http://support.ghost.org/public-api-beta\\n\\nTo enable this feature, visit `yourblog.com/ghost/settings/labs/` and tick the 'Public API' checkbox\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"1. Granting access to your domain\"\n}\n[/block]\nOnce you have the Public API enabled, you need to add your domain to the list of trusted domains so that it is allowed to request data from the API.\n\nA user interface for doing this will be released soon, but in the meantime, you will need to make some changes to your Ghost blog's database. If you're a [Ghost(Pro)](https://ghost.org/pricing) customer, you need to send the details of the domain you want to add to [email protected] and skip to step 2. \n\n### Don't forget to make a backup\n\nFirst things first, go to the labs section of your blog, and export a backup of your content :wink: \n\n### How to edit the database\n\nEssentially we need to add a new entry to the `client_trusted_domains` table. The instructions below describe how to do it for a blog using Sqlite3. If you run a MySQL or pg database, these commands will be a bit different. \n\nWhen you're ready, SSH to where you have Ghost running and try the command `sqlite3` to see if you have the sqlite3 command line tool installed. If not, you'll need to install it. On ubuntu that's a simple `sudo apt-get install sqlite3`, alternatively you can download sqlite from [their website](https://www.sqlite.org/download.html).\n\nOnce you've got sqlite3 working, we need to open the sqlite database. It is a good idea to stop Ghost whilst doing this. From the root of your Ghost blog, type this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"sqlite3 content/data/ghost.db\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nOnce inside your database, we need to find the client id for the `ghost-frontend` client that will be used for access:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"select * from clients;\",\n      \"language\": \"sql\"\n    }\n  ]\n}\n[/block]\nThat will list out all the clients, there should be two rows, and you need the `id` from the row containing the \"Ghost Frontend\" client. Grab or remember that number (in most cases, it is `2`).\n\nNow, we need to add a new domain to the `client_trusted_domains` table. The columns for this table are `id`, `uuid`, `client_id`, and `trusted_domain`. \n\n- `id` - The unique number of the row in the list of client_trusted_domains table\n- `uuid` - A globally unique identifier, you can get one by visiting https://www.uuidgenerator.net/.\n- `client_id` - ID of the client who will be doing the access, in our case `ghost-frontend`\n- `trusted_domain` - The url of the domain doing the accessing. This **must** include the protocol and must **not** end in a trailing slash. If you need support for more than one protocol or subdomain, each one will need its own entry.\n\nNow, to insert this information into the table, you need to perform an SQL insert statement, which will be in the form:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"insert into client_trusted_domains (uuid, client_id, trusted_domain) values ('<uuid>', '<ghost-frontend id>, '<your domain>');\",\n      \"language\": \"sql\"\n    }\n  ]\n}\n[/block]\nFor example, if the id of the `ghost-frontend` client is 2, and I want to make requests from https://my-ghost-blog.com, then the query should be:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"insert into client_trusted_domains (uuid, client_id, trusted_domain) values ('7137d1e7-5692-47ef-9dfa-bb8ca3fa2db6', 2, 'https://my-ghost-blog.com');\",\n      \"language\": \"sql\"\n    }\n  ]\n}\n[/block]\nOnce you've run that query, you can double check that it got inserted correctly by listing your client_trusted_domains table:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"select * from client_trusted_domains;\",\n      \"language\": \"sql\"\n    }\n  ]\n}\n[/block]\nIf it got inserted correctly, go ahead and log out of sqlite and re-start your Ghost blog.\n\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2. Adding the API utility to your site\"\n}\n[/block]\nNext, we will include the script to get access to the Ghost api url (`ghost.url.api()`) utility, which will be making the AJAX calls. \n\nHead to your Ghost blog and view the HTML source in the browser dev tools or source code. Between the `<head></head>` tags you should see a `<script>` tag with the `src` attribute set to `core/shared/ghost-url.min.js`, and beneath it, a snippet of code calling `ghost.init()`.  \n\nThe script tags you're looking for, should look like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- example snippet, find this in the source code of your blog -->\\n<script type=\\\"text/javascript\\\" src=\\\"https://my-ghost-blog.com/shared/ghost-url.min.js\\\"></script>\\n<script type=\\\"text/javascript\\\">\\nghost.init({\\n  clientId: \\\"ghost-frontend\\\",\\n  clientSecret: \\\"<letters-and-numbers>\\\"\\n });\\n </script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n**Note:** If your blog is running in development mode, the file won't be minified, so the URL will be `core/shared/ghost-url.js` instead.\n\nCopy and paste this entire snippet from the source of your Ghost blog, with both `<script>` tags, exactly as it is, into the website that you want to make API calls from. Test to make sure it works by using `console.log(ghost.url.api())`. It should spit out the url of your Ghost blog's api.\n\nNow you're ready to access and use the Ghost api on your external site! For details of how to use the `ghost.url.api` utility, check out the [documentation](http://themes.ghost.org/docs/ghost-url-api). For full details of what the API returns, see the [Post](doc:post), [Tag](doc:tag) and [User](doc:user) resources.\n\nA simple example, fetching 3 posts, might look like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script type=\\\"text/javascript\\\" src=\\\"https://code.jquery.com/jquery-1.11.3.min.js\\\"></script>\\n<script type=\\\"text/javascript\\\" src=\\\"https://my-ghost-blog.com/shared/ghost-url.min.js\\\"></script>\\n<script type=\\\"text/javascript\\\">\\nghost.init({\\n  clientId: \\\"ghost-frontend\\\",\\n  clientSecret: \\\"<letters-and-numbers>\\\"\\n });\\n  \\nfunction onSuccess(data) {\\n  var $result = $('#blog-posts');\\n  $.each(data.posts, function (i, post) {\\n    $result.append(\\n      '<li>' + post.title + '</li>'\\n    );\\n  });\\n}  \\n\\njQuery(document).ready(function () {\\n  $.get(\\n    ghost.url.api('posts', {limit: 3})\\n  ).done(onSuccess);\\n});\\n</script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]","category":"566d68cc5989ba0d00e3e879","createdAt":"2015-12-13T12:47:52.388Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":999,"project":"543023ed7d487022005b3ff8","slug":"ajax-calls-from-an-external-website","sync_unique":"","title":"Ajax calls from an external website","type":"basic","updates":[],"user":"542c5cfcddd3190e00228849","version":"543033227d487022005b4032","childrenPages":[]}

Ajax calls from an external website


This recipe is for you, if you have a blog located on a subdomain or subdirectory of your site and want to pull data into a different site. E.g. Your blog lives at blog.mysite.com and you want to list out the 3 most recent blog posts on mysite.com. [block:callout] { "type": "warning", "title": "Beta Feature", "body": "This recipe uses the Ghost Public API, which is currently a Beta feature and should be not be used in production. For more information on what Beta means, see http://support.ghost.org/public-api-beta\n\nTo enable this feature, visit `yourblog.com/ghost/settings/labs/` and tick the 'Public API' checkbox" } [/block] [block:api-header] { "type": "basic", "title": "1. Granting access to your domain" } [/block] Once you have the Public API enabled, you need to add your domain to the list of trusted domains so that it is allowed to request data from the API. A user interface for doing this will be released soon, but in the meantime, you will need to make some changes to your Ghost blog's database. If you're a [Ghost(Pro)](https://ghost.org/pricing) customer, you need to send the details of the domain you want to add to [email protected] and skip to step 2. ### Don't forget to make a backup First things first, go to the labs section of your blog, and export a backup of your content :wink: ### How to edit the database Essentially we need to add a new entry to the `client_trusted_domains` table. The instructions below describe how to do it for a blog using Sqlite3. If you run a MySQL or pg database, these commands will be a bit different. When you're ready, SSH to where you have Ghost running and try the command `sqlite3` to see if you have the sqlite3 command line tool installed. If not, you'll need to install it. On ubuntu that's a simple `sudo apt-get install sqlite3`, alternatively you can download sqlite from [their website](https://www.sqlite.org/download.html). Once you've got sqlite3 working, we need to open the sqlite database. It is a good idea to stop Ghost whilst doing this. From the root of your Ghost blog, type this: [block:code] { "codes": [ { "code": "sqlite3 content/data/ghost.db", "language": "shell" } ] } [/block] Once inside your database, we need to find the client id for the `ghost-frontend` client that will be used for access: [block:code] { "codes": [ { "code": "select * from clients;", "language": "sql" } ] } [/block] That will list out all the clients, there should be two rows, and you need the `id` from the row containing the "Ghost Frontend" client. Grab or remember that number (in most cases, it is `2`). Now, we need to add a new domain to the `client_trusted_domains` table. The columns for this table are `id`, `uuid`, `client_id`, and `trusted_domain`. - `id` - The unique number of the row in the list of client_trusted_domains table - `uuid` - A globally unique identifier, you can get one by visiting https://www.uuidgenerator.net/. - `client_id` - ID of the client who will be doing the access, in our case `ghost-frontend` - `trusted_domain` - The url of the domain doing the accessing. This **must** include the protocol and must **not** end in a trailing slash. If you need support for more than one protocol or subdomain, each one will need its own entry. Now, to insert this information into the table, you need to perform an SQL insert statement, which will be in the form: [block:code] { "codes": [ { "code": "insert into client_trusted_domains (uuid, client_id, trusted_domain) values ('<uuid>', '<ghost-frontend id>, '<your domain>');", "language": "sql" } ] } [/block] For example, if the id of the `ghost-frontend` client is 2, and I want to make requests from https://my-ghost-blog.com, then the query should be: [block:code] { "codes": [ { "code": "insert into client_trusted_domains (uuid, client_id, trusted_domain) values ('7137d1e7-5692-47ef-9dfa-bb8ca3fa2db6', 2, 'https://my-ghost-blog.com');", "language": "sql" } ] } [/block] Once you've run that query, you can double check that it got inserted correctly by listing your client_trusted_domains table: [block:code] { "codes": [ { "code": "select * from client_trusted_domains;", "language": "sql" } ] } [/block] If it got inserted correctly, go ahead and log out of sqlite and re-start your Ghost blog. [block:api-header] { "type": "basic", "title": "2. Adding the API utility to your site" } [/block] Next, we will include the script to get access to the Ghost api url (`ghost.url.api()`) utility, which will be making the AJAX calls. Head to your Ghost blog and view the HTML source in the browser dev tools or source code. Between the `<head></head>` tags you should see a `<script>` tag with the `src` attribute set to `core/shared/ghost-url.min.js`, and beneath it, a snippet of code calling `ghost.init()`. The script tags you're looking for, should look like this: [block:code] { "codes": [ { "code": "<!-- example snippet, find this in the source code of your blog -->\n<script type=\"text/javascript\" src=\"https://my-ghost-blog.com/shared/ghost-url.min.js\"></script>\n<script type=\"text/javascript\">\nghost.init({\n clientId: \"ghost-frontend\",\n clientSecret: \"<letters-and-numbers>\"\n });\n </script>", "language": "html" } ] } [/block] **Note:** If your blog is running in development mode, the file won't be minified, so the URL will be `core/shared/ghost-url.js` instead. Copy and paste this entire snippet from the source of your Ghost blog, with both `<script>` tags, exactly as it is, into the website that you want to make API calls from. Test to make sure it works by using `console.log(ghost.url.api())`. It should spit out the url of your Ghost blog's api. Now you're ready to access and use the Ghost api on your external site! For details of how to use the `ghost.url.api` utility, check out the [documentation](http://themes.ghost.org/docs/ghost-url-api). For full details of what the API returns, see the [Post](doc:post), [Tag](doc:tag) and [User](doc:user) resources. A simple example, fetching 3 posts, might look like this: [block:code] { "codes": [ { "code": "<script type=\"text/javascript\" src=\"https://code.jquery.com/jquery-1.11.3.min.js\"></script>\n<script type=\"text/javascript\" src=\"https://my-ghost-blog.com/shared/ghost-url.min.js\"></script>\n<script type=\"text/javascript\">\nghost.init({\n clientId: \"ghost-frontend\",\n clientSecret: \"<letters-and-numbers>\"\n });\n \nfunction onSuccess(data) {\n var $result = $('#blog-posts');\n $.each(data.posts, function (i, post) {\n $result.append(\n '<li>' + post.title + '</li>'\n );\n });\n} \n\njQuery(document).ready(function () {\n $.get(\n ghost.url.api('posts', {limit: 3})\n ).done(onSuccess);\n});\n</script>", "language": "html" } ] } [/block]
This recipe is for you, if you have a blog located on a subdomain or subdirectory of your site and want to pull data into a different site. E.g. Your blog lives at blog.mysite.com and you want to list out the 3 most recent blog posts on mysite.com. [block:callout] { "type": "warning", "title": "Beta Feature", "body": "This recipe uses the Ghost Public API, which is currently a Beta feature and should be not be used in production. For more information on what Beta means, see http://support.ghost.org/public-api-beta\n\nTo enable this feature, visit `yourblog.com/ghost/settings/labs/` and tick the 'Public API' checkbox" } [/block] [block:api-header] { "type": "basic", "title": "1. Granting access to your domain" } [/block] Once you have the Public API enabled, you need to add your domain to the list of trusted domains so that it is allowed to request data from the API. A user interface for doing this will be released soon, but in the meantime, you will need to make some changes to your Ghost blog's database. If you're a [Ghost(Pro)](https://ghost.org/pricing) customer, you need to send the details of the domain you want to add to [email protected] and skip to step 2. ### Don't forget to make a backup First things first, go to the labs section of your blog, and export a backup of your content :wink: ### How to edit the database Essentially we need to add a new entry to the `client_trusted_domains` table. The instructions below describe how to do it for a blog using Sqlite3. If you run a MySQL or pg database, these commands will be a bit different. When you're ready, SSH to where you have Ghost running and try the command `sqlite3` to see if you have the sqlite3 command line tool installed. If not, you'll need to install it. On ubuntu that's a simple `sudo apt-get install sqlite3`, alternatively you can download sqlite from [their website](https://www.sqlite.org/download.html). Once you've got sqlite3 working, we need to open the sqlite database. It is a good idea to stop Ghost whilst doing this. From the root of your Ghost blog, type this: [block:code] { "codes": [ { "code": "sqlite3 content/data/ghost.db", "language": "shell" } ] } [/block] Once inside your database, we need to find the client id for the `ghost-frontend` client that will be used for access: [block:code] { "codes": [ { "code": "select * from clients;", "language": "sql" } ] } [/block] That will list out all the clients, there should be two rows, and you need the `id` from the row containing the "Ghost Frontend" client. Grab or remember that number (in most cases, it is `2`). Now, we need to add a new domain to the `client_trusted_domains` table. The columns for this table are `id`, `uuid`, `client_id`, and `trusted_domain`. - `id` - The unique number of the row in the list of client_trusted_domains table - `uuid` - A globally unique identifier, you can get one by visiting https://www.uuidgenerator.net/. - `client_id` - ID of the client who will be doing the access, in our case `ghost-frontend` - `trusted_domain` - The url of the domain doing the accessing. This **must** include the protocol and must **not** end in a trailing slash. If you need support for more than one protocol or subdomain, each one will need its own entry. Now, to insert this information into the table, you need to perform an SQL insert statement, which will be in the form: [block:code] { "codes": [ { "code": "insert into client_trusted_domains (uuid, client_id, trusted_domain) values ('<uuid>', '<ghost-frontend id>, '<your domain>');", "language": "sql" } ] } [/block] For example, if the id of the `ghost-frontend` client is 2, and I want to make requests from https://my-ghost-blog.com, then the query should be: [block:code] { "codes": [ { "code": "insert into client_trusted_domains (uuid, client_id, trusted_domain) values ('7137d1e7-5692-47ef-9dfa-bb8ca3fa2db6', 2, 'https://my-ghost-blog.com');", "language": "sql" } ] } [/block] Once you've run that query, you can double check that it got inserted correctly by listing your client_trusted_domains table: [block:code] { "codes": [ { "code": "select * from client_trusted_domains;", "language": "sql" } ] } [/block] If it got inserted correctly, go ahead and log out of sqlite and re-start your Ghost blog. [block:api-header] { "type": "basic", "title": "2. Adding the API utility to your site" } [/block] Next, we will include the script to get access to the Ghost api url (`ghost.url.api()`) utility, which will be making the AJAX calls. Head to your Ghost blog and view the HTML source in the browser dev tools or source code. Between the `<head></head>` tags you should see a `<script>` tag with the `src` attribute set to `core/shared/ghost-url.min.js`, and beneath it, a snippet of code calling `ghost.init()`. The script tags you're looking for, should look like this: [block:code] { "codes": [ { "code": "<!-- example snippet, find this in the source code of your blog -->\n<script type=\"text/javascript\" src=\"https://my-ghost-blog.com/shared/ghost-url.min.js\"></script>\n<script type=\"text/javascript\">\nghost.init({\n clientId: \"ghost-frontend\",\n clientSecret: \"<letters-and-numbers>\"\n });\n </script>", "language": "html" } ] } [/block] **Note:** If your blog is running in development mode, the file won't be minified, so the URL will be `core/shared/ghost-url.js` instead. Copy and paste this entire snippet from the source of your Ghost blog, with both `<script>` tags, exactly as it is, into the website that you want to make API calls from. Test to make sure it works by using `console.log(ghost.url.api())`. It should spit out the url of your Ghost blog's api. Now you're ready to access and use the Ghost api on your external site! For details of how to use the `ghost.url.api` utility, check out the [documentation](http://themes.ghost.org/docs/ghost-url-api). For full details of what the API returns, see the [Post](doc:post), [Tag](doc:tag) and [User](doc:user) resources. A simple example, fetching 3 posts, might look like this: [block:code] { "codes": [ { "code": "<script type=\"text/javascript\" src=\"https://code.jquery.com/jquery-1.11.3.min.js\"></script>\n<script type=\"text/javascript\" src=\"https://my-ghost-blog.com/shared/ghost-url.min.js\"></script>\n<script type=\"text/javascript\">\nghost.init({\n clientId: \"ghost-frontend\",\n clientSecret: \"<letters-and-numbers>\"\n });\n \nfunction onSuccess(data) {\n var $result = $('#blog-posts');\n $.each(data.posts, function (i, post) {\n $result.append(\n '<li>' + post.title + '</li>'\n );\n });\n} \n\njQuery(document).ready(function () {\n $.get(\n ghost.url.api('posts', {limit: 3})\n ).done(onSuccess);\n});\n</script>", "language": "html" } ] } [/block]