# Content Documentation
> Documentation for Content
## Guides
- [APIs overview](https://developer.goacoustic.com/acoustic-content/docs/api.md)
- [Call unauthenticated and authenticated APIs](https://developer.goacoustic.com/acoustic-content/docs/test-tabs-1.md): Learn how to call Content APIs in Java, NodeJS, and Javascript
- [Develop your website](https://developer.goacoustic.com/acoustic-content/docs/roadmap-developing-your-own-website.md)
- [Custom user interfaces](https://developer.goacoustic.com/acoustic-content/docs/custom-user-interfaces.md)
- [Create an Iframe component](https://developer.goacoustic.com/acoustic-content/docs/creating-an-iframe-component.md)
- [Host web applications](https://developer.goacoustic.com/acoustic-content/docs/using-acoustic-content-to-host-web-applications.md)
- [Integrate Content palette](https://developer.goacoustic.com/acoustic-content/docs/using-the-acoustic-content-palette-in-delivery-mode.md)
- [Author content](https://developer.goacoustic.com/acoustic-content/docs/authoring-content-with-the-acoustic-content-rest-api.md)
- [Add layouts for existing content types](https://developer.goacoustic.com/acoustic-content/docs/adding-layouts-for-an-existing-content-type.md)
- [Add layouts for new content types](https://developer.goacoustic.com/acoustic-content/docs/adding-layouts-for-a-new-content-type-or-page-type.md)
- [Optimize and transform images with Akamai](https://developer.goacoustic.com/acoustic-content/docs/how-to-optimize-and-transform-your-images-automatically-with-akamai-1.md)
- [Optimize and transform images with Akamai Image Manager](https://developer.goacoustic.com/acoustic-content/docs/optimize-and-transform-images-with-akamai-image-manager.md)
- [Use image assets in web applications](https://developer.goacoustic.com/acoustic-content/docs/using-acoustic-content-image-assets-in-a-web-application.md)
- [Publish and deliver content](https://developer.goacoustic.com/acoustic-content/docs/publishing-and-delivering-content.md)
- [Render content](https://developer.goacoustic.com/acoustic-content/docs/rendering.md)
- [Render HTML pages](https://developer.goacoustic.com/acoustic-content/docs/render-an-html-article-page-with-templates-and-layout.md)
- [Search content](https://developer.goacoustic.com/acoustic-content/docs/searching-content.md)
- [Preview content](https://developer.goacoustic.com/acoustic-content/docs/preview-content.md)
- [Build your website locally](https://developer.goacoustic.com/acoustic-content/docs/setting-up-your-development-environment.md)
- [Create pages for your website](https://developer.goacoustic.com/acoustic-content/docs/creating-pages-for-your-website.md)
- [Customize the OSLO sample](https://developer.goacoustic.com/acoustic-content/docs/developing-your-own-website.md)
- [Update your Oslo sample](https://developer.goacoustic.com/acoustic-content/docs/updating-your-oslo-sample.md)
- [Customize header and footer](https://developer.goacoustic.com/acoustic-content/docs/customizing-the-oslo-sample-site-header-and-footer.md)
- [Customize site banner](https://developer.goacoustic.com/acoustic-content/docs/adding-a-new-element-to-the-banner-section.md)
- [Test your customizations](https://developer.goacoustic.com/acoustic-content/docs/test-your-customization-changeshtml.md)
- [Landing pages](https://developer.goacoustic.com/acoustic-content/docs/landing-pages.md)
- [Create landing pages](https://developer.goacoustic.com/acoustic-content/docs/creating-landing-pages-types-and-layouts.md)
- [Access site through APIs](https://developer.goacoustic.com/acoustic-content/docs/accessing-your-sites-through-acoustic-content-apis.md)
- [Customize site search](https://developer.goacoustic.com/acoustic-content/docs/customizing-site-search.md)
- [Augment the sitemap](https://developer.goacoustic.com/acoustic-content/docs/augmenting-sitemaps-with-acoustic-content.md)
- [Add analytics to your site](https://developer.goacoustic.com/acoustic-content/docs/adding-analytics-to-your-site.md)
- [Create a progressive web app](https://developer.goacoustic.com/acoustic-content/docs/converting-the-oslo-sample-site-to-a-progressive-web-application.md)
## API Reference
- [Introduction](https://developer.goacoustic.com/acoustic-content/reference/introduction.md)
- [Get started](https://developer.goacoustic.com/acoustic-content/reference/get-started.md)
- [Retrieve all assets.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-assets.md): Use this endpoint to retrieve all assets from the database.
User roles: admin, manager, editor, viewer
- [Create an asset.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-assets.md): Use this endpoint to create an asset. There are two ways to use this endpoint. The first method is to create a resource separately, then provide the resource id in the json body of the request along with any other desired data. The second method is to provide resource binary as a multipart field. Another multipart field containing any additional data can then be optionally provided. The second method allows the asset and resource to be created simultaneously. Note:- If AI tag analysis is enabled, it starts in the background. AI analyzes and provides tag recommendations for the asset that is created. ### Method 1 (Create asset and resource separately): ### #### Create the resource #### See POST /resource for details on how to create a resource. # #### Create the asset #### Create an asset by providing the resource id obtained from the previous step. Additional data about the asset can also be optionally provided. If an asset exists in the specified path, it is overwritten. The path that you provide must contain a leading slash. The path and name fields are optional and are generated from the resource’s name by default. # #### Example request body: #### ~~~ { "resource": "8d21025d21e7b3595cbf630fb9d7212b", "path": "/Screen Shot 2016-05-11 at 6.52.22 PM", "description": "Screenshot", "name": "Important screenshot", "tags": { "values": [ "screenshot" ] }, "status": "draft" } ~~~ # ### Method 2 (Create asset and resource simultaneously): ### #### Set the Content-Type header #### Set the Content-Type header to 'multipart/form-data'. # #### Set the 'resource' field on the multipart form #### The resource field on the multipart form should contain your resource binary. The following headers are required on this form part: 1. Content-Type header specifying the format of the resource. 2. The filename field on the Content-Disposition header of this form part specifying the resource name. # #### Set the 'data' field on the multipart form (optional) #### Additional data about the asset can be optionally provided. If an asset exists in the specified path, it is overwritten. The path that you provide must contain a leading slash. The path and name fields are optional and are generated from the resource’s name by default. # #### Example value in field: #### ~~~ { "path": "/Screen Shot 2016-05-11 at 6.52.22 PM", "description": "Screenshot", "name": "Important screenshot", "tags": { "values": [ "screenshot" ] }, "status": "draft" } ~~~ # #### Create the asset and resource #### Create the asset and resource simultaneously by posting the form. #
User roles: admin, manager, editor
- [Retrieve an existing asset.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-assets-id.md): Use this endpoint to retrieve an existing asset that matches the ID that is specified from the database. A conditional request is supported.
User roles: admin, manager, editor, viewer
- [Delete an existing asset.](https://developer.goacoustic.com/acoustic-content/reference/delete_authoring-v1-assets-id.md): Use this endpoint to immediately delete an existing asset from the database.
User roles: admin, manager, editor
- [Update an existing asset.](https://developer.goacoustic.com/acoustic-content/reference/put_authoring-v1-assets-id.md): Use this end-point to update an existing asset that matches the ID that is specified. A conditional request is supported. Note:- If AI tag analysis is enabled, it starts in the background. AI analyzes and provides tag recommendations for the asset that is created.
User roles: admin, manager, editor
- [Retrieve an existing asset by path.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-assets-record.md): Use this endpoint to retrieve an existing asset that matches the path that has been set. A conditional request is supported.
User roles: admin, manager, editor, viewer
- [AI analyzes the asset. The analysis results are stored on the asset itself.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-assets-id-analyze.md): Use the /assets/{id}/analyze endpoint to perform AI analysis on asset if supported.
User roles: admin, manager, editor
- [Create a draft of existing asset.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-assets-id-create-draft.md): Use this endpoint to create draft of existing asset and return the draft if successful.
User roles: admin, manager, editor
- [Retrieve all assets modified within the specified date](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-assets-views-by-modified.md): Use the /assets/views/by-modified endpoint to retrieve all assets that was modified within the date range specified.
User roles: admin, manager, editor, viewer
- [Retrieve all the taxonomies.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-categories.md): Retrieve all the taxonomies (root categories).
User roles: admin, manager, editor, viewer
- [Create a new category.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-categories.md): Create a category with the contents of the JSON body.
User roles: admin, manager
- [Retrieve an existing category item.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-categories-id.md): Retrieve the category with ID {id}.
User roles: admin, manager, editor, viewer
- [Update an existing category item.](https://developer.goacoustic.com/acoustic-content/reference/put_authoring-v1-categories-id.md): Update the category with ID {id}.
User roles: admin, manager
- [Delete an existing category item.](https://developer.goacoustic.com/acoustic-content/reference/delete_authoring-v1-categories-id.md): Delete the category with ID {id} along with all the categories under it.
User roles: admin, manager
- [Gets all categories modified between the start and end date.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-categories-views-by-modified.md): This endpoint returns a paged result view of category items modified within a range specified by start and end date.
User roles: admin, manager, editor, viewer
- [Retrieve the child categories of the category with ID {id}.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-categories-id-children.md): Retrieve the child categories of the category with ID {id}.
User roles: admin, manager, editor, viewer
- [Retrieve all the taxonomies and their children.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v2-categories.md): Retrieve all the taxonomies and thier children. Optional depth query string limits the depth of the categories returned.
User roles: admin, manager, editor, viewer
- [Mark items as ready for publishing in bulk.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-changes-status-ready.md): Use the `/changes/status/ready` endpoint to change the status of multiple items to the `ready` state. Currently only Assets and Content support for workflow states. ### Example Requests: ### #### Change the status of a content and an asset to the ready state #### Specify the items that you want to change to the ready state in the request body. ##### Request: ##### ~~~ { "ids": [ { "id": "579c2232-7398-4c8b-921d-3932bfc45d19", "classification": "content" }, { "id": "448e8d63-ed15-4d59-85e5-53908a84ca93", "classification": "asset" } ] } ~~~ #### Optionally provide a name for a set of changes. #### You can also optionally name the set of changes. ##### Request: ##### ~~~ { "name": "HalloweenContent", "ids": [ { "id": "579c2232-7398-4c8b-921d-3932bfc45d19", "classification": "content" } ] } ~~~ # #### Request with unique IDs #### Alternatively you can also make requests with the content hub unique ID. The unique ID is the items classification and the ID combined to create an ID that is unique across all content hub items. ~~~ { "ids": [ { "id": "content:579c2232-7398-4c8b-921d-3932bfc45d19" }, { "id": "asset:448e8d63-ed15-4d59-85e5-53908a84ca93" } ] } ~~~ ## Dealing with Errors: ## When the request succeeds for all items that was requested, then a `204` response is returned. However, if one or more items fail an error message is returned. # ### Error Types # __Mismatched revisions__ The revision that is provided of the item is not the current revision. Check whether you still want to proceed based on the recent state of the item and retry with recent revision. ~~~ { "uid":"content:a", "id":"a", "classification":"content", "key":"mismatched.revs.20000", "code": 20000, "parameters":{ "requestedRev": "a-1", "currentRev": "a-2" } } ~~~ # __Item is not in valid state__ Draft items are allowed to be saved with validation errors but the errors must be resolved before you can change the status from draft to ready. Resolve the validation errors and then retry the operation. ~~~ { "uid":"content:a", "id":"a", "classification":"content", "key":"invalid.item.20001", "code": 20001 } ~~~ # __Item not found__ The item that is specified was not found. Check whether the ID provided is correct, or if the item was deleted. ~~~ { "uid":"content:a", "id":"a", "classification":"content", "key":"not.found.20002", "code": 20002 } ~~~ # __Invalid Target State__ The Workflow status that this item is attempting to move to is not allowed from its current state. ~~~ { "uid":"content:a", "id":"a", "classification":"content", "key":"invalid.target.workflow.state.20003", "code": 20003, "parameters":{ "target": "ready", "current": "ready" } } ~~~ # __Workflow not supported for unmanaged assets__ Workflow actions are not supported for unmanaged developer assets. Refer to Asset documentation for clarification on managed versus unmanaged assets. ~~~ { "uid":"content:a", "id":"a", "classification":"content", "key":"unmanaged.asset.20005", "code": 20005 } ~~~ # __Dependencies Failed__ The status of the item cannot be changed because one or more of its dependencies failed. In this case, refer to the dependency error to find the root cause. ~~~ { "uid":"content:a", "id":"a", "classification":"content", "key":"dependencies.failed.20100", "code": 20100, "parameters":{ "dependencies": [ "content:b"] } } ~~~ # __Missing dependencies__ The status of the item cannot be changed because one or more of its dependencies were not specified. Review whether to include the dependent items in this operation and if so repeat the bulk request with the IDs included. ~~~ { "uid":"content:a", "id":"a", "classification":"content", "key":"missing.dependencies.20200", "code": 20200, "parameters":{ "missing": [ "asset:c" ,"asset:d"] } } ~~~ # __Generic Error__ Something unexpectedly went wrong trying to complete the action on this item. ~~~ { "uid":"asset:g", "id":"g", "classification":"asset", "key":"error.generic.1000", "code": 1000 } ~~~ ## Example responses Now some full examples ### Example 1 - Item failed due to dependency failure. Request ~~~ { "ids": [ { "id": "content:a" }, { "id": "content:b" }, { "id": "content:c" } ] } ~~~ # Response ~~~ { "missing":[], "genericErrors":["content:a"], "userErrors":["content:b"], "successful":["content:c"] "messages":{ "content:a":{ "uid":"content:a", "id":"a", "classification":"content", "key":"dependencies.failed.20100", "code": 20100, "parameters":{ "dependencies": ["content:b"] } }, "content:b":{ "uid":"content:b", "id":"b", "classification":"content", "key":"invalid.item.20001", "code": 20001 } } } ~~~ # In the example that is shown, the goal was to change the status of the items with IDs `a`, `b`, and `c` to ready state. The item with ID `c` was successfully changed to ready state, while the item with ID `b` fails due to validation errors. Since item with ID `a` has a dependency to item with ID `b`, it also fails. ***Note:*** The response provides the IDs with the various arrays to provide context on the failure. The failure for item with ID `a` is grouped into the generic errors list since there is nothing to fix with the item `a`. Instead, the user must fix the validation errors with `b` and retry to change the status to ready for `a` and `b`. # ### Example 2 - Item failed due to missing dependencies. Request ~~~ { "ids": [ { "id": "content:a" } ] } ~~~ # Response ~~~ { "missing":["asset:c", "asset:d"], "genericErrors":[], "userErrors":[], "successful":[] "messages":{ "content:a":{ "uid":"content:a", "id":"a", "classification":"content", "key":"missing.dependencies.20200", "code": 20200, "parameters":{ "missing": [ "asset:c" ,"asset:d"] } } } } ~~~ # The status of draft items cannot be changed to ready if the draft item still has draft dependencies. In the example that is shown, content `a` has a reference to asset `c` and `d`. You can repeat the request for bulk ready with all three items included. Alternatively, you can use the Authoring reference API to check and obtain the connected items before you perform the bulk ready request.
User roles: admin, manager, editor
- [Bulk retire items.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-changes-status-retire.md): Use the `/changes/status/retire` endpoint to change the status of multiple items to the retired state. Currently, only Assets and Content support workflow states. For examples of request, see the documentation for `changes/status/ready` endpoint.
User roles: admin, manager, editor
- [Beta - Bulk delete items.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-changes-delete.md): This is a Beta API it is subject to change. Use the `/changes/delete` endpoint to delete multiple items. Currently, only assets and content are supported. ## Requests Specify the items that you want to delete in the request body. # ~~~ { "ids": [ { "id": "579c2232-7398-4c8b-921d-3932bfc45d19", "classification": "content" }, { "id": "448e8d63-ed15-4d59-85e5-53908a84ca93", "classification": "asset" } ] } ~~~ # Alternatively you can also make requests with the content hub unique ID. The unique ID is the items classification and the ID combined to create an ID that is unique across all content hub items. # ~~~ { "ids": [ { "id": "content:579c2232-7398-4c8b-921d-3932bfc45d19" }, { "id": "asset:448e8d63-ed15-4d59-85e5-53908a84ca93" } ] } ~~~ ## Responses When the request succeeds for all items, then the `status` field will have the value `success`. If some items succeed, but others fail, the `status` field will have the value `partial`. If all items fail, the `status` field will have the value `failure`. # There are a number of arrays which are returned when items fail to delete. These help categorize the errors which you may want to action in different ways. In the case where all items succeed, only the `successful` array will be returned. - `successful` - Items that were successfully deleted. - `skipped` - Items which would have been deleted but were not due to other failures. Once the other failures are resolved these items should be successfully deleted. - `userError` - Items that cannot be deleted because they require must be either removed from the request or require some further user action before they can succeed. These include the following errors: - Insufficient Permissions - Drafts may be deleted by anyone, but non-draft items may ony be deleted by a manager or administrator. - Missing Dependencies - These items have other items depending on them and cannot be deleted. To delete these items, either the depency on these items must be removed, or the other items must also be deleted. - `missing` - Items that have a dependency on one or more of the items requested for deletion. - `genericErrors` - Items that the system failed to delete. The messages object contains information on the specific failure for each individual failing item. ## Examples ### Success Where a request to delete a content and an asset are successful. # #### Request ~~~ { "ids": [ { "id": "content:a" }, { "id": "asset:b" } ] } ~~~ # #### Response ~~~ { "status": "success" "successful": ["content:a", "content:b"] } ~~~ ### Partial Failure In the example that is shown, the goal was to delete items with IDs `a` and `b`. Items cannot be deleted if another item has dependency to it. In this case content `b` is referenced by asset `c`. The content item `a` is marked as skipped, where if the issue with `b` is resolved then item `a` would then be successfully deleted. Content `b` is marked as a user error and the dependant asset `c` is marked as missing. # Alternatively, you can use the authoring reference API to check and obtain the connected items before you perform the bulk delete request. # #### Request ~~~ { "ids": [ { "id": "content:a" }, { "id": "content:b" } ] } ~~~ # #### Response ~~~ { "status": "partial" "successful": [] "skipped": ["content:a"], "genericErrors": [], "userErrors": ["content:b"], "missing": ["asset:c"], "messages": { "content:b": { "uid": "content:b", "id": "b", "classification": "content", "key": "missing.dependencies.details.20201", "code": 20201, "parameters": { "missing": [ { "uid": "asset:c", "id": "c", "classification": "asset", "name": "Banner Image" } ] } } } } ~~~
User roles: admin, manager, editor
- [Beta - Bulk move items to another library.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-changes-set-library.md): This is a Beta API it is subject to change. Use the `/changes/set-library` endpoint to move multiple items to library. Currently, only assets and content are supported. Admin can move items between libraries without restrictions. Manager and Editor must be a contributor in both the source and destination libraries. ## Requests Specify the items that you want to move in the request body. Specify destination library id as well # ~~~ { "ids": [ { "id": "579c2232-7398-4c8b-921d-3932bfc45d19", "classification": "content" }, { "id": "448e8d63-ed15-4d59-85e5-53908a84ca93", "classification": "asset" } ], "libraryId": "" } ~~~ # Alternatively you can also make requests with the content hub unique ID. The unique ID is the items classification and the ID combined to create an ID that is unique across all content hub items. # ~~~ { "ids": [ { "id": "content:579c2232-7398-4c8b-921d-3932bfc45d19" }, { "id": "asset:448e8d63-ed15-4d59-85e5-53908a84ca93" } ], "libraryId": "" } ~~~ ## Responses When the request succeeds for all items, then the `status` field will have the value `success`. If all items fail, the `status` field will have the value `failure`. # There are a number of arrays which are returned when items fail to delete. These help categorize the errors which you may want to action in different ways. In the case where all items succeed, only the `successful` array will be returned. - `successful` - Items that were successfully moved. - `userError` - Items that cannot be moved because they require must be either removed from the request or require some further user action before they can succeed. Following error can occur: - Insufficient Permissions - User must have access to remove items from old library/ies and re-create them in destination library. Exception is Admin user who can move items without restrictions. - `skipped` - Items which would have been moved but were not due to other failures. Once the other failures are resolved these items should be successfully moved. - `genericErrors` - Items that the system failed to move. - `missing` - Field is present in the error response but it is never used. The messages object contains information on the specific failure for each individual failing item. ## Examples ### Success Where a request to move a content and an asset are successful. # #### Request ~~~ { "ids": [ { "id": "content:a" }, { "id": "asset:b" } ], "libraryId": "lib-id" } ~~~ # #### Response ~~~ { "status": "success" "successful": ["content:a", "content:b"] } ~~~ ### Failure In the example that is shown, the goal was to move items with IDs `a` and `b`. Items cannot be moved user has insufficient permissions. Both content itema `a` and `b` are marked as userError. # #### Request ~~~ { "ids": [ { "id": "content:a" }, { "id": "content:b" } ], "libraryId": "lib-id" } ~~~ # #### Response ~~~ { "status": "failure", "successful": [], "skipped": [], "genericErrors": [], "userErrors": [ "asset:1234", "content:5678" ], "missing": [], "messages": { "asset:1234": { "uid": "asset:1234", "id": "1234", "classification": "asset", "key": "insufficient.permissions.20010", "code": 20010, "parameters": { "items": [] } }, "content:5678": { "uid": "content:5678", "id": "5678", "classification": "content", "key": "insufficient.permissions.20010", "code": 20010, "parameters": { "items": [] } } } } ~~~
User roles: admin, manager, editor
- [Mark the item with the specified unique ID as ready for publishing.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-changes-uid-status-ready.md): Use the `/changes/{uid}/status/ready` endpoint to ready a single item with the specified unique ID. The unique ID (uid) is the items classification and the ID combined to create an ID that is unique across all items in Content. If the item is used by other draft items then you must use the Bulk ready API to mark a group of inter-dependent items as ready for publishing. Currently, only Assets and Content support workflow.
User roles: admin, manager, editor
- [Retire an item with the specified unique ID.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-changes-uid-status-retire.md): Use the `/changes/{uid}/status/retire` endpoint to retire a single item with the specified unique ID. The unique ID (uid) is the items classification and the ID combined to create an ID that is unique across all content hub items. If the item has draft dependencies then you must use the Bulk retire API to retire the group of dependent items. Currently, only Assets and Content support workflow.
User roles: admin, manager, editor
- [Mark an item with the specified classification and ID as ready for publishing.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-changes-classification-id-status-ready.md): Use the `/changes/{classification}/{id}/status/ready` endpoint to ready a single item with the specified classification and ID. If the item is used by other draft items then you must use the Bulk ready API to mark a group of inter-dependent items as ready for publishing. Currently, only Assets and Content support workflow.
User roles: admin, manager, editor
- [Retire an item with the specified classification and ID.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-changes-classification-id-status-retire.md): Use the `/changes/{classification}/{id}/status/retire` endpoint to retire a single item with the specified classification and ID. If the item has draft dependencies then you must use the Bulk retire API to retire the group of dependent items. Currently, only Assets and Content support workflow.
User roles: admin, manager, editor
- [Create a comment.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-comments.md): Use the /comments endpoint to create a comment. You must provide a message and a target to create the comment.
User roles: admin, manager, editor
- [Retrieve an existing comment.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-comments-id.md): Use the /comments/{id} endpoint to retrieve an existing comment that matches the ID that is specified from the database.
User roles: admin, manager, editor, viewer
- [Update an existing comment.](https://developer.goacoustic.com/acoustic-content/reference/put_authoring-v1-comments-id.md): Use the /comments/{id} end point to update an existing comment that matches the ID that is specified.
User roles: admin, manager, editor
- [Delete an existing comment.](https://developer.goacoustic.com/acoustic-content/reference/delete_authoring-v1-comments-id.md): Use the /comments/{id} endpoint to delete an existing comment from the database.
User roles: admin, manager, editor
- [Retrieve all comments for a specific item.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-comments-by-item-classification-id.md): Use the /comments/by-item/{classification}/{id} endpoint to fetch all comments that are associated to a specific item. Use the query parameter 'since' to fetch comments since a specific date. Conditional requests are supported.
User roles: admin, manager, editor, viewer
- [Retrieve all comments that were created by a user.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-comments-by-user-userid.md): Use the /comments/by-user/{userId} endpoint to fetch all comments that were created by the specified user. Optionally, the query parameter since can be used to fetch comments only 'since' a specific date.
User roles: admin, manager, editor, viewer
- [List all content items in the database.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-content.md): Use the /content endpoint to list all content items in the database.
User roles: admin, manager, editor, viewer
- [Create content items.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-content.md): Use the /content endpoint to create content. A content type must be specified through the typeId property. You cannot create content without a content type. ### Example: ### Creates a readied content that contains the name and birthday of a person. # ~~~ { "name": "Person", "typeId": "b0798e67-3da2-48b4-b044-016495fa3ead", "status": "ready", "elements": { "name": { "elementType": "text", "value": "Thomas Watson" }, "birthday": { "elementType": "datetime", "value": "1874-02-17T00:00:00Z" } } } ~~~
User roles: admin, manager, editor
- [Retrieve an existing content item.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-content-id.md): Use the /content/{id} endpoint to retrieve an existing content item from the database. This endpoint returns the API representation of a content item.
User roles: admin, manager, editor, viewer
- [Update an existing content item.](https://developer.goacoustic.com/acoustic-content/reference/put_authoring-v1-content-id.md): Use the /content/{id} end point to update an existing content item. You must retrieve the content item first by using the GET endpoint before you can update. This endpoint requires the full representation of the content item to update it. If there is a need to preview and/or review changes to the item prior to the update going live, first use the /content/{id}/create-draft endpoint to create a draft of the item and perform the update on the draft version. Following this, the draft may then be readied via the /content/{id}/ready endpoint to finalize the update. However, if there is no need to preview and/or review the update, then the update can be directly performed on an item with "ready" status.
User roles: admin, manager, editor
- [Delete an existing content item immediately.](https://developer.goacoustic.com/acoustic-content/reference/delete_authoring-v1-content-id.md): Use the /content/{id} endpoint to delete an existing content item in the database. If the content item that you want to delete has an active draft version, then you cannot delete it. Delete the draft version of the content item and then delete the content item.
User roles: admin, manager, editor
- [Retrieve all content of the specified type.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-content-views-by-type.md): Use the /content/views/by-type endpoint to retrieve all content items of a specified content type from the database.
User roles: admin, manager, editor, viewer
- [Retrieve all content modified within the specified date.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-content-views-by-modified.md): Use the /content/views/by-modified endpoint to retrieve all content items that was modified within the date range specified.
User roles: admin, manager, editor, viewer
- [Create a draft version of an existing content item.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-content-id-create-draft.md): Use the /content/{id}/create-draft endpoint to create a draft version of an existing content item. You can create a draft version when a content item document is in ready or retired status. If a draft of the content item already exists, you cannot create a draft.
User roles: admin, manager, editor
- [Retrieve the total number of content items in the database.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-content-count.md):
User roles: admin, manager, editor, viewer
- [AI analyzes and provides tag recommendations for the content.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-content-id-analyze.md): Use the /content/{id}/analyze endpoint to perform AI analysis on content text.
User roles: admin, manager, editor
- [Validate the specified content item against its type.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-content-id-validate.md): Use the /content/{id}/validate end-point to validate if the content item specified matches its recorded content type.
User roles: admin, manager, editor
- [Copies the specified documents.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-copy-sync.md): Use the `/authoring/v1/copy/sync` endpoint to copy the specified documents for the current tenant. Currently supported document classifications are `asset` and `content`. As for all Acoustic Content PUT and POST requests, the Content-Type header should be set to application/json.
User roles: admin, manager
- [Create new layouts.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-layouts.md): Use the /layouts end-point to create a new layout.
User roles: admin, manager
- [Retrieve all layouts in the database.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-layouts.md): Use the /layouts endpoint to retrieve all layouts from the database.
User roles: admin, manager, editor, viewer
- [Retrieves the layouts associated with the specified content.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-layouts-by-content-content-id.md): Use the /layouts/by-content/{contentId} endpoint to retrieve the layouts associated with the specified content. When the 'filter' query string parameter is set to 'selected', only the selected layout (which could be a content override) is returned.
User roles: admin, manager, editor, viewer
- [Retrieve an existing layout by its path.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-layouts-by-path.md): Use the /layouts/by-path end-point to retrieve an existing layout from the database.
User roles: admin, manager, editor, viewer
- [Retrieve the total number of layouts.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-layouts-count.md): Use the /layouts/count endpoint to obtain the total number of layouts within the database.
User roles: admin, manager, editor, viewer
- [Update an existing layout.](https://developer.goacoustic.com/acoustic-content/reference/put_authoring-v1-layouts-id.md): Use the /layouts/{id} end-point to update an existing layout within the database.
User roles: admin, manager
- [Delete an existing layout.](https://developer.goacoustic.com/acoustic-content/reference/delete_authoring-v1-layouts-id.md): Use the /layouts/{id} endpoint to delete an existing layout from the database.
User roles: admin, manager
- [Retrieve an existing layout.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-layouts-id.md): Use the /layouts/{id} end-point to retrieve an existing layout from the database.
User roles: admin, manager, editor, viewer
- [Retrieve all layouts in the database ordered by last modified date.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-layouts-views-by-modified.md): Use the /layouts/views/by-modified endpoint to retrieve all layouts from the database and list them in the order of their last modified date.
User roles: admin, manager, editor, viewer
- [Retrieve all layouts in the database with the specified name.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-layouts-views-by-name.md): Use the /layouts/views/by-name endpoint to retrieve all layouts from the database with the specified name.
User roles: admin, manager, editor, viewer
- [Create new layout mappings.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-layout-mappings.md): Use the /layout-mapping end-point to create a new layout mapping.
User roles: admin, manager
- [Retrieve all layout mappings in the database.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-layout-mappings.md): Use the /layout-mappings endpoint to retrieve all layout mappings from the database.
User roles: admin, manager, editor, viewer
- [Retrieve an existing layout mapping by its path.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-layout-mappings-by-path.md): Use the /layout-mappings/by-path end-point to retrieve an existing layout mapping from the database.
User roles: admin, manager, editor, viewer
- [Retrieve an existing layout mapping via its associated content-type.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-layout-mappings-by-type-type-id.md): Use the /layout-mappings/by-type/{type-id} end-point to retrieve an existing layout mapping from the database.
User roles: admin, manager, editor, viewer
- [Deletes an existing layout mapping via its associated content-type.](https://developer.goacoustic.com/acoustic-content/reference/delete_authoring-v1-layout-mappings-by-type-type-id.md): Use the /layout-mappings/by-type/{type-id} end-point to delete an existing layout mapping from the database.
User roles: admin, manager
- [Copies an existing layout mapping via its associated content-type.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-layout-mappings-by-type-type-id-copy.md): Use the /layout-mappings/by-type/{type-id}/copy end-point to create a duplicate of a layout mapping. The new layout mapping will have a name in the format 'Copy [NUMBER] of [SOURCE-NAME]'
User roles: admin, manager
- [Retrieve the total number of layout mappings.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-layout-mappings-count.md): Use the /layout-mappings/count endpoint to obtain the total number of layout mappings within the database.
User roles: admin, manager, editor, viewer
- [Update an existing layout mapping.](https://developer.goacoustic.com/acoustic-content/reference/put_authoring-v1-layout-mappings-id.md): Use the /layout-mappings/{id} end-point to update an existing layout mapping within the database.
User roles: admin, manager
- [Delete an existing layout mapping.](https://developer.goacoustic.com/acoustic-content/reference/delete_authoring-v1-layout-mappings-id.md): Use the /layout-mappings/{id} endpoint to delete an existing layout mapping from the database.
User roles: admin, manager
- [Retrieve an existing layout mapping.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-layout-mappings-id.md): Use the /layout-mappings/{id} end-point to retrieve an existing layout mapping from the database.
User roles: admin, manager, editor, viewer
- [Copies an existing layout mapping.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-layout-mappings-id-copy.md): Use the /layout-mappings/{id}/copy end-point to create a duplicate of a layout mapping. The new layout mapping will have a name in the format 'Copy [NUMBER] of [SOURCE-NAME]'
User roles: admin, manager
- [Retrieve all layout mappings in the database ordered by last modified date.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-layout-mappings-views-by-modified.md): Use the /layout-mappings/views/by-modified endpoint to retrieve all layout mappings from the database and list them in the order of their last modified date.
User roles: admin, manager, editor, viewer
- [Retrieve all layout mappings in the database with the specified name.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-layout-mappings-views-by-name.md): Use the /layout-mappings/views/by-name endpoint to retrieve all layout mappings from the database with the specified name.
User roles: admin, manager, editor, viewer
- [Retrieve the outgoing references for items.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-references-outgoing.md): Use the `/references/outgoing` endpoint to retrieve outgoing references for items. This endpoint allows batch lookups by allowing multiple items to be looked at the same time ### Examples: ### #### A simple lookup of the outgoing references for one item #### The default depth to look for references in an item is `1`. If it is `depth.reached` and there are more references that are found in the item, the result `code` that is returned indicates that there are more references. You can then either query at a higher depth or query for all items which have non empty `excluded` arrays. The results are returned in a key value format with the `references` field where the key is the content hub ID of the item. In Graph terminology, each element in the references object is a Node and the array of IDs in the `included` array on each Node is an outgoing edge to another node. ##### Request: ##### ~~~ { "root" : "content:0e28db52-a916-49ea-9bde-9f014bc6f691" } ~~~ ##### Response: ##### ~~~ { "root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "result": { "status": "ok", "depth": 1 }, "next": { "roots": [ [ "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0" ] ], "filters": { "filterType": "include", "classifications": [], "statuses": [] }, "depth": 1, "metadata": true, "fl": [] }, "references": { "content:81baa86e-ee94-45de-8e90-b23d8ef84e45": { "id": "81baa86e-ee94-45de-8e90-b23d8ef84e45", "classification": "content", "included": [], "excluded": [ "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0" ] }, "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca": { "id": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "classification": "content-type", "included": [], "excluded": [] }, "content:0e28db52-a916-49ea-9bde-9f014bc6f691": { "id": "0e28db52-a916-49ea-9bde-9f014bc6f691", "classification": "content", "included": [ "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "content:81baa86e-ee94-45de-8e90-b23d8ef84e45" ], "excluded": [] } } } ~~~ #### A simple lookup of the outgoing references for one item with metadata #### Instead of just getting a graph of content hub IDs, you can also request to retrieve metadata for each item. The metadata returned are the default fields that are returned by the authoring search API (`authoring/v1/search`). ##### Request: ##### ~~~ { "root" : "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "metadata" : true } ~~~ ##### Response: ##### ~~~ { "root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "result": { "status": "ok", "depth": 1 }, "references": { "content:81baa86e-ee94-45de-8e90-b23d8ef84e45": { "id": "81baa86e-ee94-45de-8e90-b23d8ef84e45", "classification": "content", "metadata": { "id": "content:81baa86e-ee94-45de-8e90-b23d8ef84e45", "name": "Slide7", "classification": "content", "type": "Slide", "typeId": "cad2e430-beed-40d0-bb57-1c86c4f912c0", "locale": "en", "lastModified": "2017-06-09T01:21:31.369Z", "lastModifier": "Thomas Watson", "lastModifierId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "created": "2017-06-09T01:21:17.630Z", "creator": "Thomas Watson", "creatorId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "status": "ready" }, "included": [], "excluded": [ "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0" ] }, "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca": { "id": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "classification": "content-type", "metadata": { "id": "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "name": "Slideshow", "classification": "content-type", "lastModified": "2017-06-09T01:18:08.301Z", "lastModifier": "Thomas Watson", "lastModifierId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "created": "2017-06-09T01:15:56.578Z", "creator": "Thomas Watson", "creatorId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "status": "ready" }, "included": [], "excluded": [] }, "content:0e28db52-a916-49ea-9bde-9f014bc6f691": { "id": "0e28db52-a916-49ea-9bde-9f014bc6f691", "classification": "content", "metadata": { "id": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "name": "MySlideshow", "classification": "content", "type": "Slideshow", "typeId": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "locale": "en", "lastModified": "2017-06-09T01:22:34.049Z", "lastModifier": "Thomas Watson", "lastModifierId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "created": "2017-06-09T01:18:58.426Z", "creator": "Thomas Watson", "creatorId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "status": "ready" }, "included": [ "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "content:81baa86e-ee94-45de-8e90-b23d8ef84e45" ], "excluded": [] } } } ~~~ #### Using fl parameter to request specific metadata fields #### Just like the search API, the `fl` parameter can be used to request specific fields, which include the `document` field, which is the entire API representation of the item. Note: When the `fl` parameter is used, the `id` field is also always returned. ##### Request: ##### ~~~ { "root" : "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "metadata" : true, "fl" : ["name"] } ~~~ ##### Response: ##### ~~~ { "root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "result": { "status": "ok", "depth": 1 }, "references": { "content:81baa86e-ee94-45de-8e90-b23d8ef84e45": { "id": "81baa86e-ee94-45de-8e90-b23d8ef84e45", "classification": "content", "metadata": { "id": "content:81baa86e-ee94-45de-8e90-b23d8ef84e45", "name": "Slide7" }, "included": [], "excluded": [ "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0" ] }, "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca": { "id": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "classification": "content-type", "metadata": { "id": "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "name": "Slideshow" }, "included": [], "excluded": [] }, "content:0e28db52-a916-49ea-9bde-9f014bc6f691": { "id": "0e28db52-a916-49ea-9bde-9f014bc6f691", "classification": "content", "metadata": { "id": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "name": "MySlideshow" }, "included": [ "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "content:81baa86e-ee94-45de-8e90-b23d8ef84e45" ], "excluded": [] } } } ~~~ #### Multiple items can be looked up at once by specifying multiple roots #### Note: Items are not duplicated twice in the references map. It is just a key value of content hub ID to data. ##### Request: ##### ~~~ { "roots" : [ "content:7015a689-91df-407e-9c1b-39ead6c37e89", "content:af988817-fcae-4070-a987-93cb99e4f81d"] } ~~~ ##### Response: ##### ~~~ { "roots": [ "content:7015a689-91df-407e-9c1b-39ead6c37e89", "content:af988817-fcae-4070-a987-93cb99e4f81d" ], "result": { "status": "ok", "depth": 1 }, "references": { "content:7015a689-91df-407e-9c1b-39ead6c37e89": { "id": "7015a689-91df-407e-9c1b-39ead6c37e89", "classification": "content", "included": [ "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0" ], "excluded": [] }, "content:af988817-fcae-4070-a987-93cb99e4f81d": { "id": "af988817-fcae-4070-a987-93cb99e4f81d", "classification": "content", "included": [ "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0" ], "excluded": [] }, "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0": { "id": "cad2e430-beed-40d0-bb57-1c86c4f912c0", "classification": "content-type", "included": [], "excluded": [] } } } ~~~ #### Using Filters #### You can use some basic filters based on the item type such as content or asset and based on the status of the item such as ready or draft. For example, when you use the filter "content" it returns only items of type content. ##### Request: ##### ~~~ { "root":"content:0e28db52-a916-49ea-9bde-9f014bc6f691", "filters":{ "classifications":[ "content" ] } } ~~~ ##### Response: ##### ~~~ { "root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "result": { "status": "ok", "depth": 1 }, "references": { "content:81baa86e-ee94-45de-8e90-b23d8ef84e45": { "id": "81baa86e-ee94-45de-8e90-b23d8ef84e45", "classification": "content", "included": [], "excluded": [] }, "content:0e28db52-a916-49ea-9bde-9f014bc6f691": { "id": "0e28db52-a916-49ea-9bde-9f014bc6f691", "classification": "content", "included": [ "content:81baa86e-ee94-45de-8e90-b23d8ef84e45" ], "excluded": [] } } } ~~~
User roles: admin, manager, editor, viewer
- [Retrieve the outgoing references for an item with the provided ID.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-references-outgoing-classification-id.md): Use the /references/outgoing/{classification}/{id} endpoint to retrieve outgoing references for an item with the provided ID. The usage is similar to the batch outgoing reference endpoint (/reference/outgoing/) except the parameters are passed through query parameters and only one item can be requested at a time. ### Examples: ### #### A simple lookup of the outgoing references for one item #### The default depth to look for references in an item is `1`. If it is `depth.reached` and there are more references that are found in the item, the result `code` that is returned indicates that there are more references. You can either query at a higher depth or query for all items, which have non empty `excluded` arrays. The results are returned in a key value format with the `references` field where the key is the content hub ID of the item. In Graph terminology, each element in the references object is a Node and the array of IDs in the `included` array on each Node is an outgoing edge to another node. ##### Request: ##### ~~~ "{baseURL}/authoring/v1/references/outgoing/content/0e28db52-a916-49ea-9bde-9f014bc6f691" ~~~ ##### Response: ##### ~~~ { "root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "result": { "status": "ok", "depth": 1 }, "next": { "roots": [ [ "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0" ] ], "filters": { "filterType": "include", "classifications": [], "statuses": [] }, "depth": 1, "fl": [] }, "references": { "content:81baa86e-ee94-45de-8e90-b23d8ef84e45": { "id": "81baa86e-ee94-45de-8e90-b23d8ef84e45", "classification": "content", "included": [], "excluded": [ "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0" ] }, "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca": { "id": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "classification": "content-type", "included": [], "excluded": [] }, "content:0e28db52-a916-49ea-9bde-9f014bc6f691": { "id": "0e28db52-a916-49ea-9bde-9f014bc6f691", "classification": "content", "included": [ "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "content:81baa86e-ee94-45de-8e90-b23d8ef84e45" ], "excluded": [] } } } ~~~ #### A simple lookup of the outgoing references for one item with metadata #### Instead of just getting a graph of content hub IDs, you can also request to retrieve metadata for each item. The metadata returned are the default fields that are returned by authoring search API (`authoring/v1/search`). ##### Request: ##### ~~~ { "{baseURL}/authoring/v1/references/outgoing/content/0e28db52-a916-49ea-9bde-9f014bc6f691?include=metadata" } ~~~ ##### Response: ##### ~~~ { "root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "result": { "status": "ok", "depth": 1 }, "references": { "content:81baa86e-ee94-45de-8e90-b23d8ef84e45": { "id": "81baa86e-ee94-45de-8e90-b23d8ef84e45", "classification": "content", "metadata": { "id": "content:81baa86e-ee94-45de-8e90-b23d8ef84e45", "name": "Slide7", "classification": "content", "type": "Slide", "typeId": "cad2e430-beed-40d0-bb57-1c86c4f912c0", "locale": "en", "lastModified": "2017-06-09T01:21:31.369Z", "lastModifier": "Thomas Watson", "lastModifierId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "created": "2017-06-09T01:21:17.630Z", "creator": "Thomas Watson", "creatorId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "status": "ready" }, "included": [], "excluded": [ "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0" ] }, "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca": { "id": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "classification": "content-type", "metadata": { "id": "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "name": "Slideshow", "classification": "content-type", "lastModified": "2017-06-09T01:18:08.301Z", "lastModifier": "Thomas Watson", "lastModifierId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "created": "2017-06-09T01:15:56.578Z", "creator": "Thomas Watson", "creatorId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "status": "ready" }, "included": [], "excluded": [] }, "content:0e28db52-a916-49ea-9bde-9f014bc6f691": { "id": "0e28db52-a916-49ea-9bde-9f014bc6f691", "classification": "content", "metadata": { "id": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "name": "MySlideshow", "classification": "content", "type": "Slideshow", "typeId": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "locale": "en", "lastModified": "2017-06-09T01:22:34.049Z", "lastModifier": "Thomas Watson", "lastModifierId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "created": "2017-06-09T01:18:58.426Z", "creator": "Thomas Watson", "creatorId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "status": "ready" }, "included": [ "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "content:81baa86e-ee94-45de-8e90-b23d8ef84e45" ], "excluded": [] } } } ~~~ #### Using fl parameter to request specific metadata fields #### Just like the search API, the `fl` parameter can be used to request specific fields, which include the `document` field, which is the entire API representation of the item. Note: When the `fl` parameter is used, the `id` field is also always returned. ##### Request: ##### ~~~ { "{baseURL}/authoring/v1/references/outgoing/content/0e28db52-a916-49ea-9bde-9f014bc6f691?include=metadata&fl=name" } ~~~ ##### Response: ##### ~~~ { "root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "result": { "status": "ok", "depth": 1, "code": "depth.reached", "message": "Requested max level of 1 reached" }, "references": { "content:81baa86e-ee94-45de-8e90-b23d8ef84e45": { "id": "81baa86e-ee94-45de-8e90-b23d8ef84e45", "classification": "content", "metadata": { "id": "content:81baa86e-ee94-45de-8e90-b23d8ef84e45", "name": "Slide7" }, "included": [], "excluded": [ "content-type:cad2e430-beed-40d0-bb57-1c86c4f912c0" ] }, "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca": { "id": "bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "classification": "content-type", "metadata": { "id": "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "name": "Slideshow" }, "included": [], "excluded": [] }, "content:0e28db52-a916-49ea-9bde-9f014bc6f691": { "id": "0e28db52-a916-49ea-9bde-9f014bc6f691", "classification": "content", "metadata": { "id": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "name": "MySlideshow" }, "included": [ "content-type:bd078b79-7e1a-49e0-b3dd-e2540ac93eca", "content:81baa86e-ee94-45de-8e90-b23d8ef84e45" ], "excluded": [] } } } ~~~ #### Using Filters #### You can use some basic filters based on the item type such as content or asset and based on the status of the item such as ready or draft. For example, when you use the filter "content" it returns only items of type content. ##### Request: ##### ~~~ "{baseURL}/authoring/v1/references/outgoing/content/0e28db52-a916-49ea-9bde-9f014bc6f691?classifications=content" ~~~ ##### Response: ##### ~~~ { "root": "content:0e28db52-a916-49ea-9bde-9f014bc6f691", "result": { "status": "ok", "depth": 1 }, "references": { "content:81baa86e-ee94-45de-8e90-b23d8ef84e45": { "id": "81baa86e-ee94-45de-8e90-b23d8ef84e45", "classification": "content", "included": [], "excluded": [] }, "content:0e28db52-a916-49ea-9bde-9f014bc6f691": { "id": "0e28db52-a916-49ea-9bde-9f014bc6f691", "classification": "content", "included": [ "content:81baa86e-ee94-45de-8e90-b23d8ef84e45" ], "excluded": [] } } } ~~~
User roles: admin, manager, editor, viewer
- [Retrieve the incoming references for items.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-references-incoming.md): Use the `/references/incoming` endpoint to retrieve incoming references for items. This endpoint allows batch lookups by allowing multiple items to be looked at the same time ### Examples: ### #### A simple lookup of the incoming references for one item #### The results are returned in a key value format with the `references` field where the key is the content hub ID of the item. In Graph terminology, each element in the references object is a Node and the array of IDs in the `included` array on each Node is an incoming edge to another node. ##### Request: ##### ~~~ { "root": "content:3e01a155-458e-4428-b24f-d91bfdd2c991" } ~~~ ##### Response: ##### ~~~ { "references": { "content:3e01a155-458e-4428-b24f-d91bfdd2c991": [ { "uid": "content:7a061c8b-7fef-4fc9-89b0-6255f09697c6", "id": "7a061c8b-7fef-4fc9-89b0-6255f09697c6", "classification": "content", "metadata": { "name": "Clean design" } }, { "uid": "content:d01c64ee-0927-457a-a1e8-809c22a1f5cf", "id": "d01c64ee-0927-457a-a1e8-809c22a1f5cf", "classification": "content", "metadata": { "name": "Editor's choice list sample" } } ] } } ~~~ #### Multiple items can be looked up at once by specifying multiple roots #### Note: Items are not duplicated twice in the references map. It is just a key value of content hub ID to data. ##### Request: ##### ~~~ { "roots":[ "content:3e01a155-458e-4428-b24f-d91bfdd2c991", "content:2d81b7e0-9a01-42aa-8c2a-b181d1abde8f", "page:9f32901d-95e5-4c2a-b136-a92bd2f370ae" ] } ~~~ ##### Response: ##### ~~~ { "references": { "content:3e01a155-458e-4428-b24f-d91bfdd2c991": [ { "uid": "content:7a061c8b-7fef-4fc9-89b0-6255f09697c6", "id": "7a061c8b-7fef-4fc9-89b0-6255f09697c6", "classification": "content", "metadata": { "name": "Clean design" } }, { "uid": "content:d01c64ee-0927-457a-a1e8-809c22a1f5cf", "id": "d01c64ee-0927-457a-a1e8-809c22a1f5cf", "classification": "content", "metadata": { "name": "Editor's choice list sample" } } ], "content:2d81b7e0-9a01-42aa-8c2a-b181d1abde8f": [ { "uid": "content:3872b3c8-f0f4-4eb4-8192-c6952cd8fd00", "id": "3872b3c8-f0f4-4eb4-8192-c6952cd8fd00", "classification": "content", "metadata": { "name": "Home" } }, { "uid": "content:a05c4497-8d13-4a3a-8624-fcf48fad6288", "id": "a05c4497-8d13-4a3a-8624-fcf48fad6288", "classification": "content", "metadata": { "name": "Search results sample" } }, { "uid": "content:ccc36bbc-791c-4212-b9e2-94b25080f36d:draft", "id": "ccc36bbc-791c-4212-b9e2-94b25080f36d:draft", "classification": "content", "metadata": { "name": "MyTestPage" } } ], "page:9f32901d-95e5-4c2a-b136-a92bd2f370ae": [] } } ~~~ #### Query on multiple roots with limit #### ##### Request: ##### ~~~ { "limit":1, "roots":[ "content:3e01a155-458e-4428-b24f-d91bfdd2c991", "content:2d81b7e0-9a01-42aa-8c2a-b181d1abde8f", "page:9f32901d-95e5-4c2a-b136-a92bd2f370ae" ] } ~~~ ##### Response: ##### ~~~ { "references": { "content:3e01a155-458e-4428-b24f-d91bfdd2c991": [ { "uid": "content:7a061c8b-7fef-4fc9-89b0-6255f09697c6", "id": "7a061c8b-7fef-4fc9-89b0-6255f09697c6", "classification": "content", "metadata": { "name": "Clean design" } } ], "content:2d81b7e0-9a01-42aa-8c2a-b181d1abde8f": [ { "uid": "content:3872b3c8-f0f4-4eb4-8192-c6952cd8fd00", "id": "3872b3c8-f0f4-4eb4-8192-c6952cd8fd00", "classification": "content", "metadata": { "name": "Home" } } ], "page:9f32901d-95e5-4c2a-b136-a92bd2f370ae": [] } } ~~~
User roles: admin, manager, editor, viewer
- [Retrieve the incoming references for an item with the provided ID.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-references-incoming-classification-id.md): Use the `/references/incoming/{classification}/{id}` endpoint to retrieve the incoming references for an item with the provided ID. ### Examples: ### #### A simple lookup of the incoming references for one item #### ##### Request: ##### ~~~ "{baseURL}/authoring/v1/references/incoming/content-type/cad2e430-beed-40d0-bb57-1c86c4f912c0" ~~~ ##### Response: ##### ~~~ { "offset": 0, "limit": 200, "href": "/authoring/v1/references/incoming/content-type/cad2e430-beed-40d0-bb57-1c86c4f912c0?offset=0&limit=200", "items": [ { "id": "2107a014-51f7-4161-96e2-d8eac6ad7dd9", "classification": "content" }, { "id": "367a067a-d49e-4a40-b16a-18442fd3b6ba", "classification": "content" } ] } ~~~ #### A simple lookup of the incoming references for one item with metadata #### Instead of just getting the content hub IDs, you can also request to retrieve metadata for each item. The metadata returned are the default fields that are returned by authoring search API (`authoring/v1/search`). ##### Request: ##### ~~~ "{baseURL}/authoring/v1/references/incoming/content-type/cad2e430-beed-40d0-bb57-1c86c4f912c0?include=metadata" ~~~ ##### Response: ##### ~~~ { "offset": 0, "limit": 200, "href": "/authoring/v1/references/incoming/content-type/cad2e430-beed-40d0-bb57-1c86c4f912c0?offset=0&limit=200", "items": [ { "id": "2107a014-51f7-4161-96e2-d8eac6ad7dd9", "classification": "content", "metadata": { "id": "content:2107a014-51f7-4161-96e2-d8eac6ad7dd9", "name": "Slide6", "classification": "content", "type": "Slide", "typeId": "cad2e430-beed-40d0-bb57-1c86c4f912c0", "locale": "en", "lastModified": "2017-06-09T04:09:35.622Z", "lastModifier": "Thomas Watson", "lastModifierId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "created": "2017-06-09T01:21:07.524Z", "creator": "Thomas Watson", "creatorId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "status": "ready", "thumbnail": "/authoring/v1/resources/28dcd9c49b0d45fb8c7bf045cc0582db?fit=inside%7C220:145" } }, { "id": "367a067a-d49e-4a40-b16a-18442fd3b6ba", "classification": "content", "metadata": { "id": "content:367a067a-d49e-4a40-b16a-18442fd3b6ba", "name": "Slide2", "classification": "content", "type": "Slide", "typeId": "cad2e430-beed-40d0-bb57-1c86c4f912c0", "locale": "en", "lastModified": "2017-06-09T01:20:20.757Z", "lastModifier": "Thomas Watson", "lastModifierId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "created": "2017-06-09T01:20:13.104Z", "creator": "Thomas Watson", "creatorId": "8bd88336-648c-46a6-80d4-73c0e81fb4fa", "status": "ready" } } ] } ~~~ #### Using fl parameter to request specific metadata fields #### Just like the search API, the `fl` parameter can be used to request specific fields including the `document` field, which is the entire API representation of the item. Note: When the `fl` parameter is used, the `id` field is also always returned. ##### Request: ##### ~~~ "{baseURL}/authoring/v1/references/incoming/content-type/cad2e430-beed-40d0-bb57-1c86c4f912c0?include=metadata&fl=name" ~~~ ##### Response: ##### ~~~ { "offset": 0, "limit": 200, "href": "/authoring/v1/references/incoming/content-type/cad2e430-beed-40d0-bb57-1c86c4f912c0?offset=0&limit=200", "items": [ { "id": "2107a014-51f7-4161-96e2-d8eac6ad7dd9", "classification": "content", "metadata": { "id": "content:2107a014-51f7-4161-96e2-d8eac6ad7dd9", "name": "Slide6" } }, { "id": "367a067a-d49e-4a40-b16a-18442fd3b6ba", "classification": "content", "metadata": { "id": "content:367a067a-d49e-4a40-b16a-18442fd3b6ba", "name": "Slide2" } } ] } ~~~
User roles: admin, manager, editor, viewer
- [Retrieve all renditions in the database.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-renditions.md): Use this endpoint to list all the renditions in the database.
User roles: admin, manager, editor, viewer
- [Create a new rendition.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-renditions.md): Use this endpoint to create a new rendition. The rendition will have resizing parameters applied before the crop is conducted. The generated rendition link will depend on the parameters provided. The scale parameter is required to resize. LocationX, locationY, width and height parameters are required to crop.
User roles: admin, manager, editor
- [Retrieve an existing rendition.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-renditions-id.md): Use this endpoint to retrieve an existing rendition from the database. Access the rendition applied through the media link. The generated rendition link will depend on the parameters provided. The scale parameter is required to resize. LocationX, locationY, width and height parameters are required to crop.
User roles: admin, manager, editor, viewer
- [Retrieve all renditions created within the specified date range.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-renditions-views-by-created.md): Use this endpoint to retrieve all renditions that was created within the date range specified.
User roles: admin, manager, editor, viewer
- [Create new image profiles.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-image-profiles.md): Use the /image-profiles end-point to create a new image profile.
User roles: admin, manager
- [Retrieve all image profiles in the database.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-image-profiles.md): Use the /image-profiles endpoint to retrieve all image profiles from the database.
User roles: admin, manager, editor, viewer
- [Retrieve the total number of image profiles.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-image-profiles-count.md): Use the /image-profiles/count endpoint to obtain the total number of image profiles within the database.
User roles: admin, manager, editor, viewer
- [Update an existing image profile.](https://developer.goacoustic.com/acoustic-content/reference/put_authoring-v1-image-profiles-id.md): Use the /image-profiles/{id} end-point to update an existing image profile within the database.
User roles: admin, manager
- [Delete an existing image profile.](https://developer.goacoustic.com/acoustic-content/reference/delete_authoring-v1-image-profiles-id.md): Use the /image-profiles/{id} endpoint to delete an existing image profile from the database.
User roles: admin, manager
- [Retrieve an existing image profile.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-image-profiles-id.md): Use the /image-profiles/{id} end-point to retrieve an existing image profile from the database.
User roles: admin, manager, editor, viewer
- [Retrieve all image profiles in the database ordered by last modified date.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-image-profiles-views-by-modified.md): Use the /image-profiles/views/by-modified endpoint to retrieve all image profiles from the database and list them in the order of their last modified date.
User roles: admin, manager, editor, viewer
- [Create a new resource.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-resources.md): Use this endpoint to create a new resource with the binary data that is provided in the request body. If the md5 checksum parameter is provided, the uploaded resource is validated against the provided checksum.
User roles: admin, manager, editor
- [Retrieve an existing resource.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-resources-id.md): Use this endpoint to retrieve an existing resource from the database. The media type of the binary is defined in the Content-Type header. Byte serving is supported. The Cache-Control response header is set to expire the resource in a year.
User roles: admin, manager, editor, viewer
- [Create a resource at the given id.](https://developer.goacoustic.com/acoustic-content/reference/put_authoring-v1-resources-id.md): Use this end point to create a resource at the required ID with the binary data provided in the request body. If a resource already exists with that id, then the md5 checksum is compared. If it matches, then the request will respond with a 200 OK. If it does not match, a 409 Conflict response is returned. The created resource will be validated against the checksum.
User roles: admin, manager, editor
- [Retrieve all resources created within the specified date range.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-resources-views-by-created.md): Use this endpoint to retrieve all resources that was created within the date range specified.
User roles: admin, manager, editor, viewer
- [Start a review.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-review.md): Use the /review endpoint to start a review. Currently, only Assets and Contents can be reviewed. This endpoint updates the status of the items in bulk. Items with the updated status are added in the review model. Check whether the items were successfully added to the review model from the items field in the returned API representation of review model. You can identify the items that failed to update or invalid items by checking the item IDs that are listed in the response header.
User roles: admin, manager, editor
- [Retrieve an existing review.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-review-id.md): Use the /review/{id} endpoint to retrieve an existing review that matches the ID that is specified from the database. This endpoint returns the API representation of the requested review.
User roles: admin, manager, editor, viewer
- [Update an existing review.](https://developer.goacoustic.com/acoustic-content/reference/put_authoring-v1-review-id.md): Use the /review/{id} end point to update an existing review that matches the ID that is specified.
User roles: admin, manager, editor
- [Delete an existing review.](https://developer.goacoustic.com/acoustic-content/reference/delete_authoring-v1-review-id.md): Use the /review/{id} endpoint to delete an existing review in the database.
User roles: admin, manager, editor
- [Approve items in a review.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-review-id-approve.md): Use the /review/{id}/approve endpoint to approve items in the specified review. This endpoint approves the items that you specify that were added to the specified review in bulk. For example, if Content A, Content B, and Asset C were added to a review, and you requested approval for Content A and Asset C, then only the items that you requested are approved. Check whether the items were successfully approved from the approvals field in the returned API representation of review model. You can identify the items that failed to approve by checking the item IDs that are listed in the response header. The review is automatically complete when all items that were requested for approval are approved.
User roles: admin, manager, editor
- [Approve all items in a review.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-review-id-approve-all.md): Use the /review/{id}/approve-all endpoint to approve all items in the specified review. This endpoint approves all the items added to the specified review in bulk. For example, if Content A, Content B, and Asset C were added to a review, then all three items in the review are approved. Check whether the items were successfully approved from the approvals field in the returned API representation of review model. You can identify the items that failed to approve by checking the item IDs that are listed in the response header. The review is automatically complete when all items are approved.
User roles: admin, manager, editor
- [Complete a review.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-review-id-complete.md): Use the /review/end/{id} endpoint to end a review. This endpoint changes the review status to complete. The approved items in the review remain as approved, whereas the status of the unapproved items in the review will change to in progress status.
User roles: admin, manager, editor
- [Search in the authoring collection](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-search.md): Performs a search query by passing all query parameters to Solr. The supported query parser for the "defType" parameter can be "edismax" or "lucene". The query parser name defined in "q" or "fq" parameter through "{! ...}" can have the value "join", "lucene", "edismax", or "geofilt". For more information about the query syntax and the available query parameters, see the Solr documentation. ### ***Limitation of sort and pagination*** ### Sorting on not unique fields can cause paging to return duplicate or missing entries in subsequent pages of results. If an index modification (adding or removing documents) which affects the sequence of ordered documents matching a query occurs in between two requests from a client for subsequent pages of results then it is possible that these modifications can result in the same document being returned on multiple pages, or documents being "skipped" as the result set shrinks or grows. It's recommended to sort by unique field or a combination ex. sort=lastModied desc, status desc. ### ***Description of the authoring collection schema*** ### The table below lists the **Name** of each field from the authoring collection. Additionally, it contains a **Description** of each field along with the following information: * **JSON Data Type:** This column specifies the data type of field values that Content returns in the result of a query. * **Solr Field Type:** This column specifies how Content stores values of the field in the authoring collection. * **boolean:** This field type is based on the Solr *BoolField* class. * **date:** This field type is based on the Solr *TrieDateField* class. * **int:** This field type is based on the Solr *TrieIntField* class. * **long:** This field type is based on the Solr *TrieLongField* class. * **location_rpt:** This field type is based on the Solr *LatLonPointSpatialField* class. * **path_hierarchical_index:** This field type is based on the Solr *TextField* class. It uses a hierarchical path tokenizer to index field values. * **string:** This field type is based on the Solr *StrField* class. * **string_ci:** This field type is based on the Solr *TextField* class. It is a case insensitive version of *string* field type. * **text_general:** This field type is based on the Solr *TextField* class. * **Indexed:** This column specifies whether you can use values of the field in a query to retrieve matching documents. * **Stored:** This column specifies whether you can retrieve the actual value of the field using a query. The fields ***highlighted*** in this column are included in the query result by default. To override that default field list, use the "fl" parameter in your query. | Name | Description | JSON Data Type | Solr Field Type | Indexed | Stored* | |------------------|-------------|----------------|-----------------|---------|---------| | assetType | For assets, this field contains the asset type. The value that is returned can be "document", "file", "image", or "video". | string | string_ci | true | ***true*** | | categories | The list of all category selections for the asset or content. All category selection elements on content are merged into this property. | array of strings | path_hierarchical_index | true | ***true*** | | categoryLeaves | The list of all leaf category selection elements for the asset or content. | array of strings | string_ci | true | false | | classification | This field describes the kind of item. The value that is returned can be "asset", "category", "content", "content-type", "image-profile", or "taxonomy". | string | string_ci | true | ***true*** | | created | The creation date of the item. | string | date | true | ***true*** | | creator | The name of the user who created the item. | string | string_ci | true | ***true*** | | creatorId | The UUID of the user that created the item. | string | string | true | ***true*** | | description | The description of the item. | string | text_general | true | ***true*** | | document | For assets and content, this field contains the full JSON document for the item. | string | string | false | true | | fileName | For assets, the name of the file that is uploaded to Content. This name is also used when you download the an image, rather than the asset name. | string | string_ci | true | ***true*** | | fileSize | For assets, this field contains the file size in bytes. | number | int | true | ***true*** | | height | For images, this field contains the height. | number | int | true | ***true*** | | id | The identifier of the item. It consists of the classification and the ID separated by a colon. This identifier is unique. | string | string | true | ***true*** | | isManaged | For assets and content, this field specifies whether the content is managed or not managed and whether the asset is a managed asset or a so-called non-managed web asset. | boolean | boolean | true | false | | keywords | The list of keywords related to the item. | array of strings | string_ci | true | ***true*** | | lastModified | The last modification date of the item. | string | date | true | ***true*** | | lastModifier | The name of the user who last modified the item. | string | string_ci | true | ***true*** | | lastModifierId | The UUID of the user that last modified the item. | string | string | true | ***true*** | | locale | The language for which the item was created. | string | string_ci | true | ***true*** | | location | For assets, this field contains the folder path without the file name. This allows for efficient queries for sibling assets. | string | string_ci | true | false | | locationPaths | For assets, this field contains all of the path segments. This allows for efficient queries that return assets in subfolders of the queried value. For example, the query *locationPaths:"/dxdam"* will return assets that are stored in the */dxdam* folder or any subfolder. | string | path_hierarchical_index | true | false | | locations | For content, this field contains an array of strings. Each string consists of the latitude and the longitude of a Location element of the content item. For example, this field contains ["48.666259, 9.039273", "53.418880, -6.416081"] for a content item with two Location elements. | array of strings | location_rpt | true | ***true*** | | media | For assets, this field contains the URL to the binary of the asset. It is relative to the API URL for your tenant. | string | string_ci | true | ***true*** | | mediaType | For assets, this field contains the media type. | string | string | true | ***true*** | | name | The name of the item. | string | string_ci | true | ***true*** | | path | For assets, this field contains the folder path including file name. | string | string_ci | true | ***true*** | | renditionCount | For image profiles, this field contains the number of renditions. | number | int | true | ***true*** | | resource | For assets, this field contains the ID of the related resource. You can use this resource ID with the authoring and delivery resource service REST APIs. | string | string | true | ***true*** | | status | For assets and content, this field contains the state the item is in. The value of this field can be "draft", "ready" or "retired". | string | string_ci | true | ***true*** | | tags | The list of tags assigned to the item. | array of strings | string_ci | true | ***true*** | | text | For content, this field is a collection of field names and text fragments that make up the item. It facilitates full-text search. | array of strings | text_general | true | false | | thumbnail | For assets, this field contains the URL to the thumbnail of the asset. It is relative to the API URL for your tenant. | string | string_ci | true | ***true*** | | type | For content, this field contains the name of the content type. | string | string_ci | true | ***true*** | | typeId | For content, this field contains the ID of the content type. | string | string_ci | true | ***true*** | | width | For images, this field contains the width. | number | int | true | ***true*** | \* **Note:** Temporarily, the authoring collection might store field values even though the table above indicates otherwise. ### ***Search Query Examples*** ### #### **Using a wildcard in the search term** #### In this example, the request URL defines a query using the standard query syntax. The "name" field is specified as the query field. The search term contains a wildcard to match any name that starts with the word "Red", for example "Red clover" or "Red_clover.pdf". The "numFound" property from the response provides the number of documents that match the query. The value of the "documents" property contains the documents from the authoring collection selected by the query. Each document is returned with its stored fields as explained in the description of the authoring collection schema. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?q=name:Red* ~~~ ##### *Response:* ##### ~~~ { "numFound": 4, "documents": [ { "id": "asset:53876d53-fbcf-45cf-8d53-f640c93f55c0", "name": "Red_clover.jpg", "classification": "asset", "assetType": "image", "description": "This is an image of a red clover plant.", "lastModified": "2017-06-27T14:49:12.160Z", "lastModifier": "John Doe", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:09.197Z", "creator": "John Doe", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "status": "ready", "resource": "b110f3efdb6e1d305a88348b1caca710", "path": "/dxdam/53/53876d53-fbcf-45cf-8d53-f640c93f55c0/Red_clover.jpg", "mediaType": "image/jpeg", "fileSize": 25513, "width": 330, "height": 440, "fileName": "Red_clover.jpg", "thumbnail": "/authoring/v1/resources/b110f3efdb6e1d305a88348b1caca710?fit=inside%7C220:145", "media": "/authoring/v1/resources/b110f3efdb6e1d305a88348b1caca710.jpg", "tags": [ "red clover", "clover", "alpine clover", "pink color", "plant", "purple color", "herb" ] }, { "id": "asset:7001cf29-b28b-4462-9b4a-827ab15eaff4", "name": "Red_clover.pdf", "classification": "asset", "assetType": "file", "description": "Description of the red clover.", "lastModified": "2017-06-27T14:49:14.409Z", "lastModifier": "Jane Doe", "lastModifierId": "7129fa28-0d25-4162-9400-cbc5c294dacc", "created": "2017-06-27T14:49:13.130Z", "creator": "John Doe", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "status": "ready", "resource": "14da685e6f1c2c67b26d5a0c80bc2be8", "path": "/dxdam/70/7001cf29-b28b-4462-9b4a-827ab15eaff4/Red_clover.pdf", "mediaType": "application/pdf", "fileSize": 331680, "keywords": [ "red clover", "Trifolium pratense", "red clover flowers", "red clover rust", "Red Clover Pollination", "Red Clover Tea", "South America" ], "fileName": "Red_clover.pdf", "media": "/authoring/v1/resources/14da685e6f1c2c67b26d5a0c80bc2be8.pdf", "tags": [ "Trifolium pratense", "US Department of Agriculture", "American Cancer Society", "Europe", "Clover", "Western Asia", "South America", "Africa" ] }, { "id": "asset:454581ee-d0f1-4eb3-9ac6-3ce4990cce24", "name": "Red_clover_herbarium.jpg", "classification": "asset", "assetType": "image", "description": "This is an image of the red clover from an herbarium.", "lastModified": "2017-06-27T14:49:13.608Z", "lastModifier": "Jane Doe", "lastModifierId": "7129fa28-0d25-4162-9400-cbc5c294dacc", "created": "2017-06-27T14:49:11.157Z", "creator": "John Doe", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "status": "ready", "resource": "e7cd2cac2e5bfce2878a707377bf42d6", "path": "/dxdam/45/454581ee-d0f1-4eb3-9ac6-3ce4990cce24/Red_clover_herbarium.jpg", "mediaType": "image/jpeg", "fileSize": 557238, "width": 1601, "height": 2200, "fileName": "Red_clover_herbarium.jpg", "thumbnail": "/authoring/v1/resources/e7cd2cac2e5bfce2878a707377bf42d6?fit=inside%7C220:145", "media": "/authoring/v1/resources/e7cd2cac2e5bfce2878a707377bf42d6.jpg", "tags": [ "olive green color", "plant", "clover", "herbarium", "sage green color" ] }, { "id": "content:c65a949c-5822-49bb-ad5d-647cd9820c57", "name": "Red clover", "classification": "content", "description": "This content provides information on the red clover.", "type": "Plant", "typeId": "357e5d59-be20-4fe5-ba9e-31913f6fc229", "locale": "en", "lastModified": "2017-06-27T14:49:36.389Z", "lastModifier": "Jane Doe", "lastModifierId": "7129fa28-0d25-4162-9400-cbc5c294dacc", "created": "2017-06-27T14:49:36.389Z", "creator": "John Doe", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "status": "ready", "categories": [ "Plant classification/Plantae/Angiosperms/Eudicots/Rosids/Fabales/Fabaceae/Faboideae/Trifolieae/Trifolium", "Plant habitats/Grassland/Meadow/Wet meadow" ], "tags": [ "clover", "purple", "luck", "pink" ] } ] } ~~~ #### **Specifying the fields to return** #### This example demonstrates the use of the "fl" parameter. It defines that only the "name" field and the "classification" field will be returned for each document matching the query. The number of returned documents is limited to 10 by default. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?q=tags:thistle&fl=name&fl=classification ~~~ ##### *Response:* ##### ~~~ { "numFound": 12, "documents": [ { "name": "Spiny_sowthistle.jpg", "classification": "asset" }, { "name": "Spiny_sowthistle.pdf", "classification": "asset" }, { "name": "Common_sowthistle.pdf", "classification": "asset" }, { "name": "Common_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Common_sowthistle.jpg", "classification": "asset" }, { "name": "Spiny sowthistle", "classification": "content" }, { "name": "Common sowthistle", "classification": "content" }, { "name": "Spiny_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Marsh_thistle.jpg", "classification": "asset" }, { "name": "Marsh_thistle_herbarium.jpg", "classification": "asset" } ] } ~~~ #### **Limiting the number of results and returned fields** #### In this example, the maximum number of documents to include in the query result is limited to 5. By default, if you do not specify the "rows" parameter, the service returns a maximum of 10 documents. The "fl" parameter defines that only the "name" field and the "classification" field will be returned for each document matching the quey. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?q=tags:thistle&fl=name&fl=classification&rows=5 ~~~ ##### *Response:* ##### ~~~ { "numFound": 12, "documents": [ { "name": "Spiny_sowthistle.jpg", "classification": "asset" }, { "name": "Spiny_sowthistle.pdf", "classification": "asset" }, { "name": "Common_sowthistle.pdf", "classification": "asset" }, { "name": "Common_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Common_sowthistle.jpg", "classification": "asset" } ] } ~~~ #### **Paging through the query result** #### In this example, the "rows" parameter is still set to 5 to limit the number of documents returned by the query. The "start" parameter defines an absolute offset of 3 in the complete sorted list of matches. Therefore, the result of the query includes documents 4 through 8 from a total of 12 documents that match the query. If an index modification (adding or removing) which affects the sequence of ordered documents matching a query occurs in between two requests from a client for subsequent pages of results then it is possible that these modifications can result in the same document being returned on multiple pages, or documents being "skipped" as the result set shrinks or grows. For more information about sorting and paging see the Solr documentation. The default value of the "start" parameter is 0. ##### *Request:* ##### ~~~ {baseURL}/authpring/v1/search?q=tags:thistle&fl=name&fl=classification&rows=5&start=3 ~~~ ##### *Response:* ##### ~~~ { "numFound": 12, "documents": [ { "name": "Common_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Common_sowthistle.jpg", "classification": "asset" }, { "name": "Spiny sowthistle", "classification": "content" }, { "name": "Common sowthistle", "classification": "content" }, { "name": "Spiny_sowthistle_herbarium.jpg", "classification": "asset" } ] } ~~~ #### **Sorting the query result** #### In this example, the query contains the "sort" parameter to sort the query result by "name" in an ascending order. The response includes the first 5 documents from the sorted query result. If an index modification (such as adding or removing documents) which affects the sequence of ordered documents matching a query occurs in between two requests from a client for subsequent pages of results, then it is possible that these modifications can result in the same document being returned on multiple pages, or documents being "skipped" as the result set shrinks or grows. It's recommended to sort by unique field or their combination ex: sort=name asc, lastModified asc ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?q=tags:thistle&fl=name&fl=classification&rows=5&sort=name asc,lastModified asc ~~~ ##### *Response:* ##### ~~~ { "numFound": 12, "documents": [ { "name": "Common sowthistle", "classification": "content" }, { "name": "Common_sowthistle.jpg", "classification": "asset" }, { "name": "Common_sowthistle.pdf", "classification": "asset" }, { "name": "Common_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Marsh thistle", "classification": "content" } ] } ~~~ #### **Getting only the number of matching documents** #### This example demonstrates how you can limit the response to only the number of documents that match the query by adding the "rows" parameters with a value of 0. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?q=*:*&rows=0 ~~~ ##### *Response:* ##### ~~~ { "numFound": 169 } ~~~ #### **Using boolean operators in a query** #### This example demonstrates the use of a boolean operator to combine different conditions in the query. This particular query returns Content "content" that is tagged with "dandelion". The fields of matching documents that are included in the response are limited to "name", "classification", and "tags". ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?q=classification:content AND tags:dandelion&fl=name&fl=classification&fl=tags ~~~ ##### *Response:* ##### ~~~ { "numFound": 1, "documents": [ { "name": "Common dandelion", "classification": "content", "tags": [ "dandelion", "yellow", "tortoise" ] } ] } ~~~ #### **Getting the "document" field as JSON object** #### In this example, the query is extended by an additional "fl" parameter to also retrieve the "document" field. To return the value of that specific field as JSON object, the "[json]" qualifier is added. By default, the field value is returned as an escaped JSON string. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?q=classification:content AND tags:dandelion&fl=name&fl=classification&fl=tags&fl=document:[json] ~~~ ##### *Response:* ##### ~~~ { "numFound": 1, "documents": [ { "name": "Common dandelion", "classification": "content", "tags": [ "dandelion", "yellow", "tortoise" ], "document": { "id": "662c212c-e8f6-4dcc-b4fa-cddb76aac7c0", "name": "Common dandelion", "description": "This content provides information on the common dandelion.", "classification": "content", "typeId": "357e5d59-be20-4fe5-ba9e-31913f6fc229", "locale": "en", "lastModified": "2017-06-27T14:49:35.361Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:35.361Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "dandelion", "yellow", "tortoise" ], "status": "ready", "elements": { "source": { "elementType": "link", "linkURL": "https://en.wikipedia.org/wiki/Taraxacum_officinale", "linkText": "Wikipedia" }, "scientificClassification": { "elementType": "category", "categoryIds": [ "e7411413986ff741cb4495df45e4b7a1" ], "categories": [ "Plant classification/Plantae/Angiosperms/Eudicots/Asterids/Asterales/Asteraceae/Cichorioideae/Cichorieae/Taraxacum" ] }, "attachment": { "elementType": "file", "asset": { "id": "ba56e2b8-c7bf-4f45-b791-323f85fdfbc5", "resourceUri": "/authoring/v1/resources/623912367a4183a13fd53be2ad9d65e9", "fileSize": 485686, "fileName": "Common_dandelion.pdf", "mediaType": "application/pdf" } }, "commonNames": { "elementType": "text", "value": "common dandelion,dandelion" }, "binomialName": { "elementType": "text", "value": "taraxacum officinale" }, "herbariumSpecimenDate": { "elementType": "datetime", "value": "1999-10-02T22:00:00Z" }, "photo": { "elementType": "image", "renditions": { "default": { "renditionId": "1d9c8fd6-5d82-477c-bf5c-08ef8bd3f9c8", "source": "/authoring/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91" } }, "asset": { "id": "16ae839a-5c79-4d83-bc80-14fa794c890f", "resourceUri": "/authoring/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91", "fileName": "Common_dandelion.jpg", "fileSize": 24800, "mediaType": "image/jpeg" } }, "description": { "elementType": "text", "value": "Taraxacum officinale is a flowering herbaceous perennial plant of the family Asteraceae (Compositae).\n\nIt can be found growing in temperate regions of the world, in lawns, on roadsides, on disturbed banks and shores of water ways, and other areas with moist soils. T. officinale is considered a weed, especially in lawns and along roadsides, but it is sometimes used as a medical herb and in food preparation. Common dandelion is well known for its yellow flower heads that turn into round balls of silver tufted fruits that disperse in the wind called \"blowballs\" or \"clocks\" (in both British and American English).\n\nTaraxacum officinale grows from generally unbranched taproots and produces one to more than ten stems that are typically 5–40 cm (2.0–15.7 in) tall, but sometimes up to 70 cm (28 in) tall. The stems can be tinted purplish, they are upright or lax, and produce flower heads that are held as tall or taller than the foliage. The foliage may be upright-growing or horizontally spreading; the leaves have petioles that are either unwinged or narrowly winged. The stems can be glabrous or sparsely covered with short hairs. Plants have milky latex and the leaves are all basal; each flowering stem lacks bracts and has one single flower head. The yellow flower heads lack receptacle bracts and all the flowers, which are called florets, are ligulate and bisexual. In many lineages, fruits are mostly produced by apomixis, notwithstanding the flowers are visited by many types of insects.\n\nThe leaves are 5–45 cm (2.0–17.7 in) long and 1–10 cm (0.39–3.94 in) wide, and are oblanceolate, oblong, or obovate in shape, with the bases gradually narrowing to the petiole. The leaf margins are typically shallowly lobed to deeply lobed and often lacerate or toothed with sharp or dull teeth.\n\nThe calyculi (the cuplike bracts that hold the florets) are composed of 12 to 18 segments: each segment is reflexed and sometimes glaucous. The lanceolate shaped bractlets are in two series, with the apices acuminate in shape. The 14–25 mm (0.55–0.98 in) wide involucres are green to dark green or brownish-green, with the tips dark gray or purplish. The florets number 40 to over 100 per head, having corollas that are yellow or orange-yellow in color.\n\nThe fruits, called cypselae, range in color from olive-green or olive-brown to straw-colored to grayish, they are oblanceoloid in shape and 2–3 mm (0.079–0.118 in) long with slender beaks. The fruits have 4 to 12 ribs that have sharp edges. The silky pappi, which form the parachutes, are white to silver-white in color and around 6 mm wide. Plants typically have 24 or 40 pairs of chromosomes, while some have 16 or 32 pairs." }, "herbariumSpecimenLocality": { "elementType": "category", "categoryIds": [ "e7cd2cac2e5bfce2878a7073777b0e78" ], "categories": [ "Plant habitats/Grassland/Meadow/Wet meadow" ] }, "herbariumSpecimenPhoto": { "elementType": "image", "renditions": { "default": { "renditionId": "2be697cd-30df-4f1d-afc8-ac17fa0ab5a0", "source": "/authoring/v1/resources/b110f3efdb6e1d305a88348b1ca4d530" }, "medium": { "renditionId": "eb688f20-2fb0-414f-a6aa-8f6e0f8a61b3", "source": "/authoring/v1/resources/b110f3efdb6e1d305a88348b1ca4d530?resize=800px:1100px&crop=800:1100;0,0" }, "large": { "renditionId": "112f0a63-72b0-4b39-b769-c7bdadcae542", "source": "/authoring/v1/resources/b110f3efdb6e1d305a88348b1ca4d530?resize=1200px:1650px&crop=1200:1650;0,0" }, "small": { "renditionId": "4a06a904-64cd-4942-ae1b-1b15389e48e2", "source": "/authoring/v1/resources/b110f3efdb6e1d305a88348b1ca4d530?resize=400px:550px&crop=400:550;0,0" } }, "asset": { "id": "852c1de4-661e-4a18-9ba8-bb49c65c50a6", "resourceUri": "/authoring/v1/resources/b110f3efdb6e1d305a88348b1ca4d530", "fileName": "Common_dandelion_herbarium.jpg", "fileSize": 695051, "mediaType": "image/jpeg" } } }, "type": "Plant", "creator": "John Doe", "lastModifier": "John Doe", "rev": "1-58a14c32fbe1af22dd368c10a350d401" } } ] } ~~~ #### **Getting documents including all available stored fields** #### In this example, the query matches all Content items of type "asset" that are tagged with "dandelion". The response includes the first document matching the query and provides all stored fields that are available for that document. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?q=classification:asset AND tags:dandelion&fl=*&rows=1&fl=document:[json] ~~~ ##### *Response:* ##### ~~~ { "numFound": 3, "documents": [ { "id": "asset:16ae839a-5c79-4d83-bc80-14fa794c890f", "name": "Common_dandelion.jpg", "classification": "asset", "assetType": "image", "description": "This is an image of a common dandelion plant.", "lastModified": "2017-06-27T14:49:20.045Z", "lastModifier": "John Doe", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:18.152Z", "creator": "John Doe", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "status": "ready", "resource": "14da685e6f1c2c67b26d5a0c80b2ed91", "path": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg", "location": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f", "locationPaths": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f", "mediaType": "image/jpeg", "fileSize": 24800, "width": 300, "height": 300, "fileName": "Common_dandelion.jpg", "thumbnail": "/authoring/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91?fit=inside%7C220:145", "media": "/authoring/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91.jpg", "tags": [ "hawkweed", "common dandelion", "pale yellow color", "oxtongue", "dandelion", "cat's-ear", "plant", "weed", "yellow color", "herb" ], "text": [ "common dandelion", "300x300" ], "isManaged": true, "document": { "mediaType": "image/jpeg", "name": "Common_dandelion.jpg", "path": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg", "digest": "JK500obHI3/Rq9eoL+6/mg==", "usageRights": { "categories": [] }, "assetType": "image", "lastModified": "2017-06-27T14:49:20.045Z", "description": "This is an image of a common dandelion plant.", "tags": { "values": [ "classification:hawkweed", "classification:common dandelion", "classification:pale yellow color", "classification:oxtongue", "dandelion", "classification:cat's-ear", "classification:plant", "classification:weed", "classification:yellow color", "classification:herb" ], "declined": [], "analysis": "complete", "suggested": [ "classification:common dandelion", "classification:herb", "classification:plant", "classification:cat's-ear", "classification:weed", "classification:hawkweed", "classification:pale yellow color" ] }, "altText": "common dandelion", "categoryIds": [], "fileName": "Common_dandelion.jpg", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "rev": "2-8c303149b41f473432d334432dc1c2c3", "cognitive": { "classifications": [ "common dandelion", "herb", "plant", "cat's-ear", "weed", "hawkweed", "pale yellow color" ], "faces": [], "colors": { "vibrant": "#d5b706", "muted": "#5c4c44", "darkVibrant": "#856706", "darkMuted": "#46522b" }, "status": "complete" }, "id": "16ae839a-5c79-4d83-bc80-14fa794c890f", "resource": "14da685e6f1c2c67b26d5a0c80b2ed91", "fileSize": 24800, "status": "ready", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "renditions": { "default": { "id": "r=14da685e6f1c2c67b26d5a0c80b2ed91&a=16ae839a-5c79-4d83-bc80-14fa794c890f", "source": "/authoring/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91" } }, "metadata": { "width": 300, "height": 300 }, "classification": "asset", "created": "2017-06-27T14:49:18.152Z", "links": { "self": { "href": "/authoring/v1/assets/16ae839a-5c79-4d83-bc80-14fa794c890f" }, "media": { "href": "/authoring/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91.jpg" }, "thumbnail": { "href": "/authoring/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91?fit=inside%7C220:145" } }, "creator": "John Doe", "lastModifier": "John Doe", "categories": [] }, "_version_": 1571369737461432320 } ] } ~~~ #### **Searching only in a subset of all documents** #### This example demonstrates the use of the "fq" parameter to search only in the specific subset of all documents that are classified as "asset". The filter query is a means to limit the set of documents that can be returned by a query. Restricting the query to a subset of all documents can speed up complex queries, because the filter query is cached independently from the main query. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?fq=classification:asset&q=tags:dandelion&fl=name&fl=classification ~~~ ##### *Response:* ##### ~~~ { "numFound": 3, "documents": [ { "name": "Common_dandelion.pdf", "classification": "asset" }, { "name": "Common_dandelion_herbarium.jpg", "classification": "asset" }, { "name": "Common_dandelion.jpg", "classification": "asset" } ] } ~~~ #### **Getting documents based on the last modification date** #### This example demonstrates the use of the "fq" parameter to search only in the specific subset of all documents that were modified in the last 2 days. The filter query is a means to limit the set of documents that can be returned by a query. Restricting the query to a subset of all documents can speed up complex queries, because the filter query is cached independently from the main query. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?fq=lastModified:[NOW-2DAYS/DAY TO NOW]&q=tags:thistle&fl=lastModified&fl=name ~~~ ##### *Response:* ##### ~~~ { "numFound": 4, "documents": [ { "name": "Marsh_thistle.jpg", "lastModified": "2017-07-03T08:38:50.870Z" }, { "name": "Marsh_thistle_herbarium.jpg", "lastModified": "2017-07-03T08:39:29.610Z" }, { "name": "Marsh_thistle.pdf", "lastModified": "2017-07-03T08:40:15.777Z" }, { "name": "Marsh thistle", "lastModified": "2017-07-03T08:37:10.966Z" } ] } ~~~ #### **Getting documents with a specific field not set** #### In this example, all documents are filtered to retrieve only entries that have no data set for the field 'tags'. The query returns only the 5 most recently updated documents. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?q=*:*&fq=NOT tags:[* TO *]&sort=lastModified desc&rows=5&fl=name&fl=classification&fl=lastModified ~~~ ##### *Response:* ##### ~~~ { "numFound": 98, "documents": [ { "name": "Plant habitats", "classification": "taxonomy", "lastModified": "2017-07-24T12:43:17.065Z" }, { "name": "Chelidonium", "classification": "category", "lastModified": "2017-06-27T15:00:24.342Z" }, { "name": "Taraxacum", "classification": "category", "lastModified": "2017-06-27T14:49:03.920Z" }, { "name": "Trifolium", "classification": "category", "lastModified": "2017-06-27T14:49:02.458Z" }, { "name": "Cirsium", "classification": "category", "lastModified": "2017-06-27T14:49:00.952Z" } ] } ~~~ #### **Getting documents with a specific field not set in combination with an OR clause** #### In this example, all documents are filtered to retrieve only entries that were modified in the last 21 days or that have no data set for the field 'tags'. The query returns only the 5 most recently updated documents. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?q=*:*&fq=lastModified:[NOW-21DAYS TO NOW] OR (*:* NOT tags:[* TO *])&sort=lastModified desc&rows=5&fl=name&fl=classification&fl=lastModified ~~~ ##### *Response:* ##### ~~~ { "numFound": 99, "documents": [ { "name": "Plant habitats", "classification": "taxonomy", "lastModified": "2017-07-24T12:43:17.065Z" }, { "name": "Marsh thistle", "classification": "content", "lastModified": "2017-07-03T08:37:10.966Z" }, { "name": "Chelidonium", "classification": "category", "lastModified": "2017-06-27T15:00:24.342Z" }, { "name": "Taraxacum", "classification": "category", "lastModified": "2017-06-27T14:49:03.920Z" }, { "name": "Trifolium", "classification": "category", "lastModified": "2017-06-27T14:49:02.458Z" } ] } ~~~ #### **Getting available facet terms** #### Faceted search organizes search results into categories based on terms from the indexed items. This can be useful, for example, to implement typeahead suggestions or filter functions. To enable faceting, add the "facet" parameter to the request and set its value to "true". Then use the "facet.field" parameter to specify each field to be treated as a facet. In this example, the response contains the facet terms that are available in the authoring collection for the fields "classification", "type", and "assetType". The request does not contain a query that matches any documents. Therefore, the "numFound" property from the response and the number following each facet term are 0. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType ~~~ ##### *Response:* ##### ~~~ { "numFound": 0, "facets": { "classification": [ "asset", 0, "category", 0, "content", 0, "content-type", 0, "image-profile", 0, "taxonomy", 0 ], "type": [ "plant", 0 ], "assetType": [ "file", 0, "image", 0 ] } } ~~~ #### **Getting available facet terms that contain a specific substring** #### This example demonstrates the use of the "facet.contains" parameter to retrieve only facet terms that contain a specific character or character sequence. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType&facet.contains=nt ~~~ ##### *Response:* ##### ~~~ { "numFound": 0, "facets": { "classification": [ "content", 0, "content-type", 0 ], "type": [ "plant", 0 ], "assetType": [] } } ~~~ #### **Limiting the number of returned facet terms** #### This example uses the "facet.limit" parameter to obtain only the first facet term for each selected facet. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType&facet.limit=1 ~~~ ##### *Response:* ##### ~~~ { "numFound": 0, "facets": { "classification": [ "asset", 0 ], "type": [ "plant", 0 ], "assetType": [ "file", 0 ] } } ~~~ #### **Paging through the returned facet terms** #### In this example, the "facet.limit" parameter is still set to 1 to limit the number of facet terms in the response. The "facet.offset" parameter defines an offset of 1. Therefore, the response includes the second facet term for each facet provided there are more facet terms available. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType&facet.limit=1&facet.offset=1 ~~~ ##### *Response:* ##### ~~~ { "numFound": 0, "facets": { "classification": [ "category", 0 ], "type": [], "assetType": [ "image", 0 ] } } ~~~ #### **Getting facet ranges** #### This example demonstrates the use of range faceting by adding corresponding "facet.range" parameters to the request. Range faceting is supported on date and numeric fields that support range queries. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?facet=true&facet.range=created&facet.range.start=NOW/DAY-3DAYS&facet.range.end=NOW&facet.range.gap=%2B1DAY ~~~ ##### Response: ##### ~~~ { "numFound": 0, "facet_ranges": { "created": { "counts": [ "2017-07-03T00:00:00Z", 0, "2017-07-04T00:00:00Z", 0, "2017-07-05T00:00:00Z", 0, "2017-07-06T00:00:00Z", 0 ], "gap": "+1DAY", "start": "2017-07-03T00:00:00Z", "end": "2017-07-07T00:00:00Z" } } } ~~~ #### **Getting the facet term information for a query result** #### This example shows the combination of a query and faceting. The response contains information about the usage of the selected facet terms across all documents of the query result. Among the 32 documents that match the query there are: * 24 documents with the "classification" field value set to "asset" and 8 classified as "content" * 8 documents with the content "type" field value set to "plant" * 16 documents with the "assetType" field value set to "image" and 8 assets of type "file" ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?q=name:Common*&fl=name&fl=classification&facet=true&facet.field=classification&facet.field=type&facet.field=assetType&rows=5 ~~~ ##### *Response:* ##### ~~~ { "numFound": 32, "documents": [ { "name": "Common_daisy.jpg", "classification": "asset" }, { "name": "Common_reed_herbarium.jpg", "classification": "asset" }, { "name": "Common_yarrow.jpg", "classification": "asset" }, { "name": "Common_nettle.pdf", "classification": "asset" }, { "name": "Common_silverweed.pdf", "classification": "asset" } ], "facets": { "classification": [ "asset", 24, "content", 8, "category", 0, "content-type", 0, "image-profile", 0, "taxonomy", 0 ], "type": [ "plant", 8 ], "assetType": [ "image", 16, "file", 8 ] } } ~~~ #### **Using the Extended DisMax query parser** #### The Content authoring search service REST API includes an additional query parser that supports more parameters than the standard query parser used in the previous examples. In this example, the "defType" parameter tells the service to use the "edismax" query parser. The query that matches the term "content" or "asset" is performed on the query field "classification" that is specified using the "qf" parameter. The response includes a maximum of 1 document as per "rows" parameter. ##### *Request:* ##### ~~~ {baseURL}/authoring/v1/search?q=content OR asset&defType=edismax&qf=classification&rows=1 ~~~ ##### *Response:* ##### ~~~ { "numFound": 68, "documents": [ { "id": "content:23c6a637-d5e8-4ef8-ba87-0f5c2fb2aa62", "name": "Common daisy", "classification": "content", "description": "This content provides information on the common daisy.", "type": "Plant", "typeId": "357e5d59-be20-4fe5-ba9e-31913f6fc229", "locale": "en", "lastModified": "2017-06-27T14:49:35.333Z", "lastModifier": "John Doe", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:35.333Z", "creator": "John Doe", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "status": "ready", "categories": [ "Plant classification/Plantae/Angiosperms/Eudicots/Asterids/Asterales/Asteraceae/Asteroideae/Astereae/Bellis", "Plant habitats/Grassland/Meadow/Rich pasture" ], "tags": [ "daisy", "white", "yellow" ] } ] } ~~~
User roles: admin, manager, editor, viewer
- [Search in the authoring collection using post request with json body](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-search-json.md): The request body contains an json object with search query
User roles: admin, manager, editor, viewer
- [Get list of all sites](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-sites.md): Returns a list of all sites. A default site with id 'default' exists out of the box.
User roles: admin, manager, editor, viewer
- [Create a new site](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-sites.md): Use this endpoint to create a new site. The new site can either be an initial draft site which has no associated ready version or it can be a draft of an existing ready site. The body of the request should contain the metadata for the new site. This metadata should include the site 'name', 'linkedDocId' is optional, 'id' is optional. If 'linkedDocId' is provided, then the site created will be a draft of the ready site specified in 'linkedDocId'. If 'linkedDocId' is not provided, then the site created will be an initial draft site i.e no ready version exists yet. If ID is provided, and a draft of the default site is being created it must start with default. 'linkedDocId' must be set to 'default'.
User roles: admin, manager, editor
- [Retrieve metadata for a site.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-sites-site-id.md): Retrieve the site metadata for an existing site. A default site with ID 'default' exists out-of-the-box.
User roles: admin, manager, editor, viewer
- [Update metadata for a site.](https://developer.goacoustic.com/acoustic-content/reference/put_authoring-v1-sites-site-id.md): Update the metadata for an existing site. A default site with ID 'default' exists out-of-the-box. The update data must include the `rev` and `name` metadata fields.
User roles: admin, manager, editor
- [Delete a site and the site pages](https://developer.goacoustic.com/acoustic-content/reference/delete_authoring-v1-sites-site-id.md): Use this endpoint to delete a site and the pages in that site.
User roles: admin, manager, editor
- [Promote the site and pages metadata from draft to ready status.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-sites-site-id-ready.md): Use this endpoint to change the status of a site's metadata and the metadata of all pages in the site from draft to ready.
User roles: admin, manager, editor
- [Cancel the draft site metadata undoing any modifications.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-sites-site-id-cancel.md): Use this endpoint to undo changes to the site's metadata.
User roles: admin, manager, editor
- [Bulk promote the specified page Ids in the specified site from draft to ready status.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-sites-site-id-pages-ready.md): Use this endpoint to change the status of multiple pages in a specific site from draft to ready.
User roles: admin, manager, editor
- [Get the full page hierarchy for a site.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-sites-site-id-pages.md): Use this endpoint to retrieve the full page hierarchy for site. The metadata for each page will be included. This metadata includes the position of the page relative to its peers, the ID for the page content item, an optional override layout ID to use and encoded route if query parameter included=route is specified.
User roles: admin, manager, editor, viewer
- [Create a page.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-sites-site-id-pages.md): Use this endpoint to create a page in a specified site. The body of the request should contain the metadata for the new page. This metadata should include the page 'name', optional 'position' relative to its peers and the 'contentId' or 'contentTypeId'. Specify 'contentId' to associate an existing content item with the page or specify 'contentTypeId' to create an empty content item using the specified content type. The 'position' field is optional, value is an integer value starting at 0. If not set position is set to the last sibling position. The 'layoutId' field is also optional. If not set the selected layout for the new content item will be the default layout mapped to the specified content type. If the 'layoutId' field is specified it must be the ID of an existing layout. If the specified layout is not mapped to the content type then the default layout mapped to the content type will be used instead.
User roles: admin, manager
- [Get pages modified between two dates.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-sites-site-id-pages-views-by-modified.md): Returns the page metadata for pages modified between the specified last modified date range in the site specified by `site-id`.
User roles: admin, manager, editor, viewer
- [Get a page by id.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-sites-site-id-pages-page-id.md): Returns the page metadata specified by `page-id` in the site specified by `site-id`. If the page is a root page then no parentId will be returned in the response.
User roles: admin, manager, editor, viewer
- [Delete a page.](https://developer.goacoustic.com/acoustic-content/reference/delete_authoring-v1-sites-site-id-pages-page-id.md): Deletes the page specified by `page-id` and all descendant pages in the site specified by `site-id`. By default the page and descendant pages associated content is not deleted, set 'delete-content' query parameter to 'true' to delete the page and descendant pages associated content.
User roles: admin, manager, editor
- [Update a page.](https://developer.goacoustic.com/acoustic-content/reference/put_authoring-v1-sites-site-id-pages-page-id.md): Updates the page metadata specified by `page-id` in the site specified by `site-id`. Move of a page to a different parent or repositioning with other sibling pages is not supported, use the move endpoint instead. The full page metadata must be supplied, partial updates are not supported.
User roles: admin, manager, editor
- [Move a page.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-sites-site-id-pages-move.md): Use this endpoint to move a page. The body of the request should be empty. The query parameters should include the 'sourceId', 'sourceRev', 'targetPosition', the optional 'targetId' and 'targetRev'. `sourceId` and `sourceRev` relate to the page to be moved. `targetId` and `targetRev` relate to the destination parent page. These are optional parameters, if not set it means the source page is to be moved to the site root. The `targetPosition` field is required, it is an integer value starting at 0. It cannot exceed the number of child pages of the destination parent page. If the move is successful, then the response body JSON object will contain the id and rev of the updated destination parent page (`targetId`), except in the case of moving to the site root then the response body is an empty JSON object. A refresh of the page hierarchy is recommended after moving a page to a different parent page.
User roles: admin, manager, editor
- [Promote the page from draft to ready status.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-sites-site-id-pages-page-id-ready.md): Use this endpoint to change the status of a page from draft to ready.
User roles: admin, manager, editor
- [Get a page by unique id.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-sites-pages-page-id.md): Returns the page metadata specified by unique `page-id`. This API is equalivent to `/sites/pages/{site-id/pages{page-id}` but does not require a `site-id`. If the page is a root page then no parentId will be returned in the response.
User roles: admin, manager, editor, viewer
- [Create new type documents.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-types.md): Use the /types end-point to create a new type document. ## Example elements ### Category element ``` { "key": "MyCategoryElement", "label": "My Category Element", "elementType": "category", "restrictedParents": ["63b5f83684cddba687cb41eca328a41a"], - Optional. Indicates that categories can only been chosen from the specified parent. Currently only supports a single entry. "searchKey": "string1" | "string2" | "string3" | "string4" | "sortableString1" | "sortableString2" | "sortableString3" | "sortableString4", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "helpText": "Please select a category from the list" } ``` ### Date (Date and Time) element ``` { "key": "MyDateElement", "label": "My Date Element", "elementType": "datetime", "fieldType": "date-time", "searchKey": "date1" | "date2" | "sortableDate1" | "sortableDate2", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "allowMultipleValues": true, "minimumValues": 1, "maximumValues": 50, "fieldLabel": "Date", "helpText": "Please select a date and time" } ``` ### Date (Date only) element ``` { "key": "MyDateElement", "label": "My Date Element", "elementType": "datetime", "fieldType": "date", "searchKey": "date1" | "date2" | "sortableDate1" | "sortableDate2", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "allowMultipleValues": true, "minimumValues": 1, "maximumValues": 50, "fieldLabel": "Date", "helpText": "Please select a date" } ``` ### File element ``` { "key": "MyFileElement", "label": "My File Element", "elementType": "file", "acceptType": ["plain-text", "presentation", "rich-document", "spreadsheet", "pdf-document"], - Optional. Specifies the allowed file types.. with the above list comprising the allowed values. "searchKey": "string1" | "string2" | "string3" | "string4" | "sortableString1" | "sortableString2" | "sortableString3" | "sortableString4", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "allowMultipleValues": true, "minimumValues": 1, "maximumValues": 50, "fieldLabel": "File", "helpText": "Please select a file" } ``` ### Formatted-Text element ``` { "key": "MyFormattedTextElement", "label": "My Formatted Text Element", "elementType": "formattedtext", "searchKey": "string1" | "string2" | "string3" | "string4" | "sortableString1" | "sortableString2" | "sortableString3" | "sortableString4", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "allowMultipleValues": true, "minimumValues": 1, "maximumValues": 50, "fieldLabel": "Text", "helpText": "Enter some text" } ``` ### Group element ``` { "key": "MyGroupElement", "label": "My Group Element", "elementType": "group", "typeRef": {"id":"73b5f83684cddba687cb41eca328a41a"}, - Must refer to an existing content-type whose `kind` attribute contains the value `embedded` "required": false, "allowMultipleValues": true, "minimumValues": 1, "maximumValues": 50, "fieldLabel": "Text", "helpText": "Please fill in these fields" } ``` ### Image element ``` { "key": "MyImageElement", "label": "My Image Element", "elementType": "image", "acceptType": ["jpg", "jpeg", "png", "gif", "svg"], - Optional. Specifies the allowed image types.. with the above list comprising the allowed values. "imageProfileId": "83b5f83684cddba687cb41eca328a4567", - Optional. Specifies the ID of the image profile that this element is using. If an image profile is selected, then 'svg' is no longer allowed as an acceptType. "searchKey": "string1" | "string2" | "string3" | "string4" | "sortableString1" | "sortableString2" | "sortableString3" | "sortableString4", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "allowMultipleValues": true, "minimumValues": 1, "maximumValues": 50, "fieldLabel": "Image", "helpText": "Please select an image" } ``` ### Link element ``` { "key": "MyLinkElement", "label": "My Link Element", "elementType": "link", "searchKey": "string1" | "string2" | "string3" | "string4" | "sortableString1" | "sortableString2" | "sortableString3" | "sortableString4", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "allowMultipleValues": true, "minimumValues": 1, "maximumValues": 50, "fieldLabel": "Link", "helpText": "Please select a link" } ``` ### Location element ``` { "key": "MyLocationElement", "label": "My Location element", "elementType": "location", "searchKey": "location1", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "helpText": "Please select a location" } ``` ### Number (Decimal) element ``` { "key": "MyNumberElement", "label": "My Number Element", "elementType": "number", "fieldType": "decimal", "minimum": 10.0, - Optional. Specifies the lowest accepted number. "maximum": 49.9, - Optional. Specifies the highest accepted number. "searchKey": "number1" | "number2" | "sortableNumber1" | "sortableNumber2", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "allowMultipleValues": true, "minimumValues": 1, "maximumValues": 50, "fieldLabel": "Number", "helpText": "Enter a number between 10.0 and 49.9" } ``` ### Number (Integer) element ``` { "key": "MyNumberElement", "label": "My Number Element", "elementType": "number", "fieldType": "integer", "minimum": 10, - Optional. Specifies the lowest accepted number. "maximum": 49, - Optional. Specifies the highest accepted number. "searchKey": "number1" | "number2" | "sortableNumber1" | "sortableNumber2", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "allowMultipleValues": true, "minimumValues": 1, "maximumValues": 50, "fieldLabel": "Number", "helpText": "Enter a number between 10 and 49" } ``` ### Option Selection element ``` { "key": "MyOptionSelectionElement", "label": "My Option Selection Element", "elementType": "optionselection", "options": [{"label":"Option 1", "selection": "Value 1"}, {"label":"Option 2", "selection": "Value 2"}], "searchKey": "string1" | "string2" | "string3" | "string4" | "sortableString1" | "sortableString2" | "sortableString3" | "sortableString4", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "allowMultipleValues": true, "minimumValues": 1, "maximumValues": 50, "helpText": "Enter make a selection" } ``` ### Reference element ``` { "key": "MyReferenceElement", "label": "My Reference Element", "elementType": "reference", "restrictTypes": [{"id":"23b5f83684cddba687cb41eca328a1234"}, {"id":"23fhf83684cddba687cb41eca328a6789"}], - Optional. Restricts the allowed content items, to only those from the specified content-types. "searchKey": "string1" | "string2" | "string3" | "string4" | "sortableString1" | "sortableString2" | "sortableString3" | "sortableString4", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "allowMultipleValues": true, "minimumValues": 1, "maximumValues": 50, "fieldLabel": "Reference", "helpText": "Please select an item" } ``` ### Text (Single Line) element ``` { "key": "MyTextElement", "label": "My Text Element", "elementType": "text", "minLength": 5, - Optional. Specifies the lowest number of accepted characters. Default is 0. "maxLength": 50, - Optional. Specifies the highest number of accepted characters. Default is 10000. "displayType": "singleLine", "displayWidth": 20, - Optional. Specifies the width of the text editor in characters. "searchKey": "string1" | "string2" | "string3" | "string4" | "sortableString1" | "sortableString2" | "sortableString3" | "sortableString4", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "allowMultipleValues": true, "minimumValues": 1, "maximumValues": 50, "fieldLabel": "Text", "helpText": "Enter some text between 5 and 50 characters" } ``` ### Text (Multi Line) element ``` { "key": "MyTextElement", "label": "My Text Element", "elementType": "text", "minLength": 5, - Optional. Specifies the lowest number of accepted characters. Default is 0. "maxLength": 50, - Optional. Specifies the highest number of accepted characters. Default is 10000. "displayType": "multiLine", "displayWidth": 20, - Optional. Specifies the width of the text editor in characters. "displayHeight": 10, - Optional. Specifies the number of lines shown within the text editor. "searchKey": "string1" | "string2" | "string3" | "string4" | "sortableString1" | "sortableString2" | "sortableString3" | "sortableString4", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "allowMultipleValues": true, "minimumValues": 1, "maximumValues": 50, "fieldLabel": "Text", "helpText": "Enter some text between 5 and 50 characters" } ``` ### Toggle element ``` { "key": "MyToggleElement", "label": "My Toggle element", "elementType": "toggle", "statement": "Lead in question", - Optional. Specifies the text (typically a question) to show with the toggle "searchKey": "boolean1" | "boolean2", - Optional. Indicates that the value of this element will be searchable under the specified key "helpText": "Please make a selection" } ``` ### Video element ``` { "key": "MyVideoElement", "label": "My Video Element", "elementType": "video", "acceptType": ["mp4"], - Optional. Specifies the allowed video types.. with the above list comprising the allowed values. "searchKey": "string1" | "string2" | "string3" | "string4" | "sortableString1" | "sortableString2" | "sortableString3" | "sortableString4", - Optional. Indicates that the value of this element will be searchable under the specified key "required": false, "allowMultipleValues": true, "minimumValues": 1, "maximumValues": 50, "fieldLabel": "Video", "helpText": "Please select a video" } ``` **Note:** Use the /types/new end-point to return a blank document instead of creating a new type document from scratch. To add an element to a type document, merge the element-fragment section from the element definition into the element section of the type document.
User roles: admin, manager
- [Retrieve all type documents in the database.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-types.md): Use the /types endpoint to retrieve all content type documents from the database.
User roles: admin, manager, editor, viewer
- [Retrieve an existing type by its path.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-types-by-path.md): Use the /types/by-path end-point to retrieve an existing content type from the database.
User roles: admin, manager, editor, viewer
- [Retrieve the total number of types.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-types-count.md): Use the /types/count endpoint to obtain the total number of content types within the database.
User roles: admin, manager, editor, viewer
- [Update an existing type.](https://developer.goacoustic.com/acoustic-content/reference/put_authoring-v1-types-id.md): Use the /types/{id} end-point to update an existing content type within the database.
User roles: admin, manager
- [Delete an existing type.](https://developer.goacoustic.com/acoustic-content/reference/delete_authoring-v1-types-id.md): Use the /types/{id} endpoint to delete an existing content type from the database.
User roles: admin, manager
- [Retrieve an existing type.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-types-id.md): Use the /types/{id} end-point to retrieve an existing content type from the database.
User roles: admin, manager, editor, viewer
- [Copies an existing type.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-types-id-copy.md): Use the /types/{id}/copy end-point to create a duplicate of a content type document. The new type will have a name in the format 'Copy [NUMBER] of [SOURCE-NAME]'
User roles: admin, manager
- [Returns a skeleton content item based on the specified content-type.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-types-id-new-content.md): Use the /types/{id}/new-content end-point to create a new content item applicable for the specified content type document.
User roles: admin, manager, editor, viewer
- [Retrieve the Json-Schema representation of the document.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-types-id-schema.md): Use the /types/{id}/schema end-point to get the Json-Schema of a content type document. Use the Json-Schema to validate content item documents that are created from this content type document.
User roles: admin, manager, editor, viewer
- [Validate the supplied type document instance (eg. content item) against the specified type.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-types-id-validate.md): Use the /types/{id}/validate end-point to validate if the content items specified match the content type document provided.
User roles: admin, manager, editor, viewer
- [Retrieve a blank content type.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-types-new.md): Use the /types/new end-point to get a blank content type document.
User roles: admin, manager, editor, viewer
- [Retrieve all type documents in the database ordered by last modified date.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-types-views-by-modified.md): Use the /types/views/by-modified endpoint to retrieve all type documents from the database and list them in the order of their last modified date.
User roles: admin, manager, editor, viewer
- [Retrieve all types in the database with the specified name.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-types-views-by-name.md): Use the /types/views/by-name endpoint to retrieve all types from the database with the specified name.
User roles: admin, manager, editor, viewer
- [Retrieve an existing element definition.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-elementdefs-id.md): Use the /elementdefs/{id} end-point to retrieve an existing element definition from the database. Each element definition describes a variety of element that can be added to a content type. To programmatically create a content-type, merge the 'elementFragment' attribute into the 'elements' attribute of the type, performing the following replacements: '$ELEMENT_KEY$': With the desired element key '$ELEMENT_LABEL$': With the desired element label
User roles: admin, manager, editor, viewer
- [Retrieve all element definitions in the database.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-elementdefs.md): Use the /elementdefs endpoint to retrieve all element definitions from the database. Each element definition describes a variety of element that can be added to a content type. To programmatically create a content-type, merge the 'elementFragment' attribute into the 'elements' attribute of the type, performing the following replacements: '$ELEMENT_KEY$': With the desired element key '$ELEMENT_LABEL$': With the desired element label
User roles: admin, manager, editor, viewer
- [Retrieve all versions for the specified authoring item.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-versions-classification-id.md): Use the /versions/{classification}/{id} endpoint to retrieve all the versions for the specified authoring item.
User roles: admin, manager, editor, viewer
- [Retrieve a specific version for a specific authoring item.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-versions-classification-id-timestamp.md): Use the /versions/{classification}/{id}/{timestamp} endpoint to retrieve a specific version for the specified authoring item.
User roles: admin, manager, editor, viewer
- [Restore a versioned item - currently supported for content and assets.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-versions-restore.md): Use this endpoint to restore a specific version of a content or an asset item by sending the JSON payload as the request body. The restored item will always be a draft - overwriting an existing one or creating a new one. Link to the new draft is sent as a response-header `Location`.
User roles: admin, manager, editor
- [Retrieve the current version policy.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-versions-policy.md): Use this endpoint to fetch the current version policy that determines how specific documents are versioned in the authoring system. Only the policy status is being returned at this point.
User roles: admin, manager, editor, viewer
- [Turn on the version-policy.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-versions-policy-on.md): Use this endpoint to turn on the version-policy.
User roles: admin
- [Turn off the version-policy.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-versions-policy-off.md): Use this endpoint to turn off the version-policy. It will also trigger the version clean-up.
User roles: admin
- [Disable the version-policy.](https://developer.goacoustic.com/acoustic-content/reference/post_authoring-v1-versions-policy-disable.md): Use this endpoint to disable the version-policy.
User roles: admin
- [Retrieve contextual search results from the authoring collection.](https://developer.goacoustic.com/acoustic-content/reference/get_authoring-v1-contextualsearch.md): Use the /authoring/v1/contextualsearch endpoint to retrieve contextual search results from the authoring collection based on the passed filters. See the Authoring Search documents on the Content API for details of the main search service parameters. #### Current filters * `accept-language` Searches for content with matching languages. If this filter is specified the `accept-language` request header must be specified with the ordered list of languages to search with. The search iterates through all of the languages in order until a language returns one or more matching content items or the service has completed the search for all the languages without finding any results. If the search returns content items the response header `content-language` is set to the language that returned those content items, otherwise this header is not returned in the response. * `proximity` Searches for content located within a certain radius of a specified location. `proximity` is used in combination with `distance` which is the bounding radius around the location. You can specify the location with the `position` parameter. If the parameter is not provided the location is read from the `X-Akamai-Edgescape` header. If the distance parameter is not provided distance is defaulted to 5. * `similar` Searches for content or assets that are similar to a specified item. `similar` uses the tags added by AI, a user, or included in the asset, such as image metadata tags to search. The content and assets with matching tags to the specified item are returned. Based on the number of tags that match a 'score' is calculated for each content and asset, the bigger the number of matching tags the higher the score. The results are returned as an ordered array response that starts with items with the highest `score` and lists them in a descending order. Note: Since the specified item in the query would be a perfect match, it is not returned as a result. #### Examples * **Search by proximity by using user's location:** `q`=type:article&`fl`=description&`filter`=proximity&`distance`=50 Searches all content of the type `article` and returns items that are found within 50 km of user's location. * **Search by proximity by providing a location:** `q`=type:article&`fl`=description&`filter`=proximity&`distance`=50&`position`=37.25,-5.796 Searches all content of the type `article` and returns items that are found within 50 km of the location that is specifed in the `position` parameter. * **Search by language (setting the `accept-language` request header):** `q`=type:article&`fl`=description&`filter`=accept-language `accept-language` de Searches all content of the type `article` and returns items where the language is set to `German [de]`. * **Search by language with ordered language list (setting the `accept-language` request header):** `q`=type:article&`fl`=description&`filter`=accept-language `accept-language` en,de;q=0.5 Searches all content of the type 'article` and returns items where the language is set to `English [en]`. Then, proceeds to search all content of the type `article` for `German [de]` if no content is found for `English`. * **Search for images similar to a specified image:** `q`=\*:\*&`filter`=similar&`similar-source-id`=acd-23-564-09-asdf&`similar-source-classification`=asset&fq=assetType:image&rows=100 The search returns images that are similar to the item with the specified ID (`similar-source-id`) and classification (`similar-source-classification`). The results are sorted in order of descending `score` by default. * **Search for images similar to a specified image and sort results in ascending `score` order:** `q`=\*:\*&`filter`=similar&`similar-source-id`=acd-23-564-09-asdf&`similar-source-classification`=asset&sort=score asc&fq=assetType:image&rows=100 The search returns images that are similar to the item with the specified ID (`similar-source-id`) and classification (`similar-source-classification`). The results are sorted in order of ascending score. * **Search for images similar to a specified image and sort results in ascending `lastModified` order:** `q`=\*:\*&`filter`=similar&`similar-source-id`=acd-23-564-09-asdf&`similar-source-classification`=asset&sort=lastModified asc&fq=assetType:image&rows=100 The search returns images that are similar to the item with the specified ID (`similar-source-id`) and classification (`similar-source-classification`). The results are sorted in order of ascending last modified date. * **Apply location and language filters (setting the `accept-language` request header):** `q`=type:article&`fl`=description&`filter`=proximity&`filter`=accept-language&`position`=0,0 `accept-language` en,de;q=0.5 Searches all content of the type `article` and returns items where the language is set to `English [en]` and the `location` is within a 5 km radius around the coordinates 0-degrees latitude and 0-degrees longitude. Then, proceeds to search all content of the type article for `German [de]` and `location` within a 5 km radius around the coordinates 0-degrees latitude and 0-degrees longitude if no content is found for `English` based search. * **Apply similar, location, and language filters (setting the `accept-language` request header):** `q`=\*:\*&`fl`=description&`filter`=proximity&`filter`=accept-language&`position`=0,0&`filter`=similar&`similar-source-id`=acd-23-564-09-asdf&`similar-source-classification`=content&fq=classification:content&rows=100 `accept-language` en The search returns any type of content which meets all of the following criteria: 1. `location` is within a radius of 5 km around the coordinates 0-degrees latitude and 0-degrees longitude 2. language is set to `English [de]` 3. similar to the item with specified id (`similar-source-id`) and classification (`similar-source-classification`).
User roles: admin, manager, editor, viewer
- [Retrieve contextual search results from the delivery collection](https://developer.goacoustic.com/acoustic-content/reference/get_delivery-v1-contextualsearch.md): Use the /delivery/v1/contextualsearch endpoint to retrieve contextual search results from the delivery collection based on the passed filters. See the Delivery Search documents on the Content API for details of the main search service parameters. #### Current filters * `accept-language` Searches for content with matching languages. If this filter is specified the `accept-language` request header must be specified with the ordered list of languages to search with. The search iterates through all of the languages in order until a language returns one or more matching content items or the service has completed the search for all the languages without finding any results. If the search returns content items the response header `content-language` is set to the language that returned those content items, otherwise this header is not returned in the response. * `proximity` Searches for content located within a certain radius of a specified location. `proximity` is used in combination with `distance` which is the bounding radius around the location. You can specify the location with the `position` parameter. If the parameter is not provided the location is read from the `X-Akamai-Edgescape` header. If the distance parameter is not provided distance is defaulted to 5. * `similar` Searches for content or assets that are similar to a specified item. `similar` uses the tags added by AI, a user, or included in the asset, such as image metadata tags to search. The content and assets with matching tags to the specified item are returned. Based on the number of tags that match a 'score' is calculated for each content and asset, the bigger the number of matching tags the higher the score. The results are returned as an ordered array response that starts with items with the highest `score` and lists them in a descending order. Note: Since the specified item in the query would be a perfect match, it is not returned as a result. #### Examples * **Search by proximity by using user's location:** `q`=type:article&`fl`=description&`filter`=proximity&`distance`=50 Searches all content of the type `article` and returns items that are found within 50 km of user's location. * **Search by proximity by providing a location:** `q`=type:article&`fl`=description&`filter`=proximity&`distance`=50&`position`=37.25,-5.796 Searches all content of the type `article` and returns items that are found within 50 km of the location that is specifed in the `position` parameter. * **Search by language (setting the `accept-language` request header):** `q`=type:article&`fl`=description&`filter`=accept-language `accept-language` de Searches all content of the type `article` and returns items where the language is set to `German [de]`. * **Search by language with ordered language list (setting the `accept-language` request header):** `q`=type:article&`fl`=description&`filter`=accept-language `accept-language` en,de;q=0.5 Searches all content of the type 'article` and returns items where the language is set to `English [en]`. Then, proceeds to search all content of the type `article` for `German [de]` if no content is found for `English`. * **Search for images similar to a specified image:** `q`=\*:\*&`filter`=similar&`similar-source-id`=acd-23-564-09-asdf&`similar-source-classification`=asset&fq=assetType:image&rows=100 The search returns images that are similar to the item with the specified ID (`similar-source-id`) and classification (`similar-source-classification`). The results are sorted in order of descending `score` by default. * **Search for images similar to a specified image and sort results in ascending `score` order:** `q`=\*:\*&`filter`=similar&`similar-source-id`=acd-23-564-09-asdf&`similar-source-classification`=asset&sort=score asc&fq=assetType:image&rows=100 The search returns images that are similar to the item with the specified ID (`similar-source-id`) and classification (`similar-source-classification`). The results are sorted in order of ascending score. * **Search for images similar to a specified image and sort results in ascending `lastModified` order:** `q`=\*:\*&`filter`=similar&`similar-source-id`=acd-23-564-09-asdf&`similar-source-classification`=asset&sort=lastModified asc&fq=assetType:image&rows=100 The search returns images that are similar to the item with the specified ID (`similar-source-id`) and classification (`similar-source-classification`). The results are sorted in order of ascending last modified date. * **Apply location and language filters (setting the `accept-language` request header):** `q`=type:article&`fl`=description&`filter`=proximity&`filter`=accept-language&`position`=0,0 `accept-language` en,de;q=0.5 Searches all content of the type `article` and returns items where the language is set to `English [en]` and the `location` is within a 5 km radius around the coordinates 0-degrees latitude and 0-degrees longitude. Then, proceeds to search all content of the type article for `German [de]` and `location` within a 5 km radius around the coordinates 0-degrees latitude and 0-degrees longitude if no content is found for `English` based search. * **Apply similar, location, and language filters (setting the `accept-language` request header):** `q`=\*:\*&`fl`=description&`filter`=proximity&`filter`=accept-language&`position`=0,0&`filter`=similar&`similar-source-id`=acd-23-564-09-asdf&`similar-source-classification`=content&fq=classification:content&rows=100 `accept-language` en The search returns any type of content which meets all of the following criteria: 1. `location` is within a radius of 5 km around the coordinates 0-degrees latitude and 0-degrees longitude 2. language is set to `English [de]` 3. similar to the item with specified id (`similar-source-id`) and classification (`similar-source-classification`).
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Retrieve filtered content by id in bulk](https://developer.goacoustic.com/acoustic-content/reference/post_delivery-v1-content-bulk-retrieve.md): Returns an array of requested filtered content items. Restricted content items cannot be accessed. To access those content items too, you have to use /mydelivery/v1/content/bulk_retrieve. Sample request body for retrieving id and title fields of two content items with id '7f2335cc-d91d-4f52-9e26-2d9402e463c0' and '1067771c-ec05-4671-951b-18f503953f2d': { "ids": ["7f2335cc-d91d-4f52-9e26-2d9402e463c0", "1067771c-ec05-4671-951b-18f503953f2d"], "fields": ["id", "title"] } For each `content item` requested .. * If a content item is not found for a specified `id`, the content retrieval for that id is skipped. * If a specified `field` is not found in the content, it will not be present in the response. * If no fields are specified for filtering, the whole content item is returned. * The `ids` array cannot be empty and hence, there should be at least one id specified for lookup. * A maximum of 25 content items can be retrieved at once. If the `ids` field is found to have more entries, only the first 25 content items requested are returned.
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Retrieve filtered content items by id in bulk, including restricted ones.](https://developer.goacoustic.com/acoustic-content/reference/post_mydelivery-v1-content-bulk-retrieve.md): Returns an array of requested filtered content items. This route is restricted to authenticated users and allows to access restricted content items too. Sample request body for retrieving id and title fields of two content items with id '7f2335cc-d91d-4f52-9e26-2d9402e463c0' and '1067771c-ec05-4671-951b-18f503953f2d': { "ids": ["7f2335cc-d91d-4f52-9e26-2d9402e463c0", "1067771c-ec05-4671-951b-18f503953f2d"], "fields": ["id", "title"] } For each `content item` requested .. * If a content item is not found for a specified `id`, the content retrieval for that id is skipped. * If a specified `field` is not found in the content, it will not be present in the response. * If no fields are specified for filtering, the whole content item is returned. * The `ids` array cannot be empty and hence, there should be at least one id specified for lookup. * A maximum of 25 content items can be retrieved at once. If the `ids` field is found to have more entries, only the first 25 content items requested are returned.
User roles: admin, manager, editor, viewer, authenticatedVisitor
- [Get content item](https://developer.goacoustic.com/acoustic-content/reference/get_delivery-v1-content-id.md): Returns the content item specified by `id`. Restricted content items cannot be accessed. To access those content items too, you have to use /mydelivery/v1/content/{id}.
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Get content item, including restricted ones.](https://developer.goacoustic.com/acoustic-content/reference/get_mydelivery-v1-content-id.md): Returns the content item specified by `id`. This route is restricted to authenticated users and allows to access restricted content items too.
User roles: admin, manager, editor, viewer, authenticatedVisitor
- [Applies server side rendering to the specified content item](https://developer.goacoustic.com/acoustic-content/reference/get_delivery-v1-rendering-render-content-id.md): Applies server side rendering to the specified content item
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Delivery Site By ID](https://developer.goacoustic.com/acoustic-content/reference/get_delivery-v1-rendering-sites-id.md): Provides delivery site information including site metadata and pages hierarchy
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Delivery Rendering Context By ID](https://developer.goacoustic.com/acoustic-content/reference/get_delivery-v1-rendering-context-id.md): Use the `rendering/context/{id}` endpoint to retrieve the rendering context for the specified content ID. The response contains the delivery content structure with resolved content element references. The resolution replaces content elements of type reference with the referenced rendering context. It is resolved recursively if the resolved content structure contains content elements of type reference. **Cycle detection** Referenced content can have cycles. In a cyclic structure, references link back to itself, often through references in between. The API detects and stops cycles to serialize the content structure. If a cycle is detected, the API stops the replacements of the referenced elements and sets a cycle marker property instead. The cycle marker property has the key "$$CYCLE" and the value of the detected cycling content ID. The content ID can be used to find the referenced content structure in the parent hierarchy.
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Aggregated type information by ID](https://developer.goacoustic.com/acoustic-content/reference/get_delivery-v1-rendering-type-id.md): Aggregated type information by ID
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Delivery Rendering Contexts By Search Query](https://developer.goacoustic.com/acoustic-content/reference/get_delivery-v1-rendering-search.md): Use the `/delivery/v1/rendering/search` endpoint to retrieve rendering contexts based on a search query. The API has the same query functionality as the delivery search API (See the delivery search API documentation for full query options), except for the following aspects: - The "fl" (field list) query parameter is ignored. - The query supports only classifiction content. - The results of the query are rendering contexts (0-*) in any case.
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Applies server side rendering to the specified content item](https://developer.goacoustic.com/acoustic-content/reference/get_mydelivery-v1-rendering-render-content-id.md): Applies server side rendering to the specified content item
User roles: admin, manager, editor, viewer, authenticatedVisitor
- [Aggregated type information by ID](https://developer.goacoustic.com/acoustic-content/reference/get_mydelivery-v1-rendering-type-id.md): Aggregated type information by ID
User roles: admin, manager, editor, viewer, authenticatedVisitor
- [Retrieve a resource by path.](https://developer.goacoustic.com/acoustic-content/reference/get_delivery-v1-resources.md): This endpoint retrieves the resource at the given path. Restricted resources cannot be accessed. To access those resources too, you have to use /mydelivery/v1/resources. The resource's path can be obtained using the Authoring assets API: /authoring/v1/assets { "items": [ { "mediaType": "image/jpeg", "name": "myPicture.jpg", "path": "/path/to/myPicture.jpg", ... The delivery URL for this endpoint would look like: /delivery/v1/resources?path=/path/to/myPicture.jpg **Note:** This endpoint should not be used for rendering published resources on a site, retrieving resources from Akamai directly is better optimized for this use case. To retrieve the resource directly from Akamai: https://[host]/[TenantID]/path/to/myPicture.jpg
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Retrieve a resource by Id.](https://developer.goacoustic.com/acoustic-content/reference/get_delivery-v1-resources-fileidentifier.md): This endpoint retrieves the resource for the specified resource Id. Restricted resources cannot be accessed. To access those resources too, you have to use /mydelivery/v1/resources/{fileIdentifier}. The resource's Id can be obtained using the Authoring assets API: /authoring/v1/assets { "items": [ { "resource": "06763fa56ceec4d5bcafb37b53de2cd1", ... The delivery Url for this endpoint would look like: /delivery/v1/resources/06763fa56ceec4d5bcafb37b53de2cd1
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Search in the delivery collection](https://developer.goacoustic.com/acoustic-content/reference/get_delivery-v1-search.md): Performs a search query by passing all query parameters to Solr. Search results will not contain protected items. The supported query parser for the "defType" parameter can be "edismax" or "lucene". The query parser name defined in "q" or "fq" parameter through "{! ...}" can have the value "join", "lucene", "edismax", or "geofilt". For more information about the query syntax and the available query parameters, see the Solr documentation. ### ***Limitation of sort and pagination*** ### Sorting on not unique fields can cause paging to return duplicate or missing entries in subsequent pages of results. If an index modification (adding or removing documents) which affects the sequence of ordered documents matching a query occurs in between two requests from a client for subsequent pages of results then it is possible that these modifications can result in the same document being returned on multiple pages, or documents being "skipped" as the result set shrinks or grows. It's recommended to sort by unique field or a combination ex. sort=lastModied desc, status desc. ### ***Description of the delivery collection schema*** ### The table below lists the **Name** of each field from the delivery collection. Additionally, it contains a **Description** of each field along with the following information: * **JSON Data Type:** This column specifies the data type of field values that Watson Content Hub returns in the result of a query. * **Solr Field Type:** This column specifies how Watson Content Hub stores values of the field in the delivery collection. * **boolean:** This field type is based on the Solr *BoolField* class. * **date:** This field type is based on the Solr *TrieDateField* class. * **int:** This field type is based on the Solr *TrieIntField* class. * **long:** This field type is based on the Solr *TrieLongField* class. * **location_rpt:** This field type is based on the Solr *LatLonPointSpatialField* class. * **path_hierarchical_index:** This field type is based on the Solr *TextField* class. It uses a hierarchical path tokenizer to index field values. * **string:** This field type is based on the Solr *StrField* class. * **string_ci:** This field type is based on the Solr *TextField* class. It is a case insensitive version of *string* field type. * **text_general:** This field type is based on the Solr *TextField* class. * **Indexed:** This column specifies whether you can use values of the field in a query to retrieve matching documents. * **Stored:** This column specifies whether you can retrieve the actual value of the field using a query. The fields ***highlighted*** in this column are included in the query result by default. To override that default field list, use the "fl" parameter in your query. | Name | Description | JSON Data Type | Solr Field Type | Indexed | Stored* | |-------------------------|-------------|----------------|-----------------|---------|---------| | aggregatedIds | For pages, this field contains the IDs that the page's appearance is made up of. This comprises the page's ID as well as the IDs of the page content item and it's directly referenced content items. Changes in one of those items will cause the page to be re-indexed. | array of strings | string_ci | true | true | | aggregatedContentIds | For pages, this field contains the content IDs that the page's appearance is made up of. This comprises the IDs of the page content item and it's directly referenced content items. Changes in one of those items will cause the page to be re-indexed. | array of strings | string_ci | true | true | | assetType | For assets, this field contains the asset type. The value that is returned can be "document", "file", "image", or "video". | string | string_ci | true | ***true*** | | boolean1 | For content, this field can contain boolean element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of booleans | boolean | true | true | | boolean2 | For content, this field can contain boolean element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of booleans | boolean | true | true | | categories | The list of all category selections for the asset or content. All category selection elements on content are merged into this property. | array of strings | path_hierarchical_index | true | ***true*** | | categoryLeaves | The list of all leaf category selection elements for the asset or content. | array of strings | string_ci | true | false | | classification | This field describes the kind of item. The value that is returned can be "asset", "category", "content" or "taxonomy". | string | string_ci | true | ***true*** | | created | The creation date of the item. | string | date | true | ***true*** | | creatorId | The UUID of the user that created the item. | string | string | true | ***true*** | | date1 | For content, this field can contain date element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of strings | date | true | true | | date2 | For content, this field can contain date element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of strings | date | true | true | | description | The description of the item. | string | text_general | true | ***true*** | | document | For assets and content, this field contains the full JSON document for the item. | string | string | false | true | | fileSize | For assets, this field contains the file size in bytes. | number | long | true | ***true*** | | generatedFiles | For content, this field contains the list of path values related to files that are generated by pre-rendering the item. | array of strings | string | true | true | | height | For images, this field contains the height. | number | int | true | true | | hideFromNavigation | For pages, this field specifies whether it should be hidden from navigation controls. | boolean | boolean | true | true | | id | The identifier of the item. For items of the same "classification", this identifier is unique. The combination of the "classification" and the "id" is unique across all items of the Watson Content Hub tenant. | string | string | true | ***true*** | | isManaged | For assets and content, this field specifies whether the content is managed or not managed and whether the asset is a managed asset or a so-called non-managed web asset. | boolean | boolean | true | false | | keywords | The list of keywords related to the item. | array of strings | string_ci | true | ***true*** | | kind | For pages, this field contains all kinds a page is assigned to. | array of strings | string_ci | true | true | | lastModified | The last modification date of the item. | string | date | true | ***true*** | | lastModifierId | The UUID of the user that last modified the item. | string | string | true | ***true*** | | locale | The language for which the item was created. | string | string_ci | true | true | | location | For assets, this field contains the folder path without the file name. This allows for efficient queries for sibling assets. | string | string_ci | true | false | | location1 | For content, this field contains an array of strings. Each string consists of the latitude and the longitude of location elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of strings | location_rpt | true | false | | locationPaths | For assets, this field contains all of the path segments. This allows for efficient queries that return assets in subfolders of the queried value. For example, the query *locationPaths:"/dxdam"* will return assets that are stored in the */dxdam* folder or any subfolder. | string | path_hierarchical_index | true | false | | locations | For content, this field contains an array of strings. Each string consists of the latitude and the longitude of a Location element of the content item. For example, this field contains ["48.666259, 9.039273", "53.418880, -6.416081"] for a content item with two Location elements. | array of strings | location_rpt | true | true | | media | For assets, this field contains the URL to the binary of the asset. It is relative to the API URL for your tenant. | string | string_ci | true | true | | mediaType | For assets, this field contains the media type. | string | string | true | ***true*** | | name | The name of the item. | string | string_ci | true | ***true*** | | number1 | For content, this field can contain number element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of numbers | double | true | true | | number2 | For content, this field can contain number element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of numbers | double | true | true | | parentId | For pages, this field contains the ID of the parent page. | string | string_ci | true | true | | path | For assets, this field contains the folder path including file name. | string | string_ci | true | ***true*** | | position | For pages, this field contains the position of the page relative to it's sibling pages. | number | int | true | true | | resource | For assets, this field contains the ID of the related resource. You can use this resource ID with the authoring and delivery resource service REST APIs. | string | string | true | ***true*** | | restricted | This field specifies whether the item is restricted. | boolean | boolean | true | false | | siteId | For pages, this field contains the ID of the site the page belongs to. | string | string_ci | true | true | | status | For assets and content, this field contains the state the item is in. The value of this field can be "ready" or "retired". | string | string_ci | true | true | | string1 | For content, this field can contain string element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of strings | string_ci | true | true | | string2 | For content, this field can contain string element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of strings | string_ci | true | true | | string3 | For content, this field can contain string element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of strings | string_ci | true | true | | string4 | For content, this field can contain string element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of strings | string_ci | true | true | | sortableDate1 | For content, this field can contain a single date element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | string | date | true | true | | sortableDate2 | For content, this field can contain a single date element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | string | date | true | true | | sortableNumber1 | For content, this field can contain a single number element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | number | double | true | true | | sortableNumber2 | For content, this field can contain a single number element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | number | double | true | true | | sortableString1 | For content, this field can contain a single string element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | string | string_ci | true | true | | sortableString2 | For content, this field can contain a single string element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | string | string_ci | true | true | | sortableString3 | For content, this field can contain a single string element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | string | string_ci | true | true | | sortableString4 | For content, this field can contain a single string element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | string | string_ci | true | true | | tags | The list of tags assigned to the item. | array of strings | string_ci | true | ***true*** | | text | For content, this field is a collection of field names and text fragments that make up the item. It facilitates full-text search. | array of strings | text_general | true | false | | thumbnail | For assets, this field contains the URL to the thumbnail of the asset. It is relative to the API URL for your tenant. | string | string_ci | true | true | | type | For content, this field contains the name of the content type. | string | string_ci | true | ***true*** | | typeId | For content, this field contains the ID of the content type. | string | string_ci | true | true | | url | For assets, this field contains the server relative URL to the binary document of the asset. For pages, it contains the URL under which the page can be adressed in an SPA. | string | string | false | ***true*** | | width | For images, this field contains the width. | number | int | true | true | \* **Note:** Temporarily, the delivery collection might store field values even though the table above indicates otherwise. ### ***Search Query Examples*** ### #### **Using a wildcard in the search term** #### In this example, the request URL defines a query using the standard query syntax. The "name" field is specified as the query field. The search term contains a wildcard to match any name that starts with the word "Red", for example "Red clover" or "Red_clover.pdf". The "numFound" property from the response provides the number of documents that match the query. The value of the "documents" property contains the documents from the delivery collection selected by the query. Each document is returned with its stored fields as explained in the description of the delivery collection schema. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?q=name:Red* ~~~ ##### *Response:* ##### ~~~ { "numFound": 4, "documents": [ { "id": "53876d53-fbcf-45cf-8d53-f640c93f55c0", "name": "Red_clover.jpg", "classification": "asset", "description": "This is an image of a red clover plant.", "lastModified": "2017-06-27T14:49:12.160Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:09.197Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "red clover", "clover", "alpine clover", "pink color", "plant", "purple color", "herb" ], "mediaType": "image/jpeg", "path": "/dxdam/53/53876d53-fbcf-45cf-8d53-f640c93f55c0/Red_clover.jpg", "fileSize": 25513, "assetType": "image", "resource": "b110f3efdb6e1d305a88348b1caca710", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/53/53876d53-fbcf-45cf-8d53-f640c93f55c0/Red_clover.jpg" }, { "id": "7001cf29-b28b-4462-9b4a-827ab15eaff4", "name": "Red_clover.pdf", "classification": "asset", "description": "Description of the red clover.", "lastModified": "2017-06-27T14:49:14.409Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:13.130Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "Trifolium pratense", "US Department of Agriculture", "American Cancer Society", "Europe", "Clover", "Western Asia", "South America", "Africa" ], "mediaType": "application/pdf", "path": "/dxdam/70/7001cf29-b28b-4462-9b4a-827ab15eaff4/Red_clover.pdf", "fileSize": 331680, "assetType": "file", "resource": "14da685e6f1c2c67b26d5a0c80bc2be8", "keywords": [ "red clover", "Trifolium pratense", "red clover flowers", "red clover rust", "Red Clover Pollination", "Red Clover Tea", "South America" ], "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/70/7001cf29-b28b-4462-9b4a-827ab15eaff4/Red_clover.pdf" }, { "id": "454581ee-d0f1-4eb3-9ac6-3ce4990cce24", "name": "Red_clover_herbarium.jpg", "classification": "asset", "description": "This is an image of the red clover from an herbarium.", "lastModified": "2017-06-27T14:49:13.608Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:11.157Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "olive green color", "plant", "clover", "herbarium", "sage green color" ], "mediaType": "image/jpeg", "path": "/dxdam/45/454581ee-d0f1-4eb3-9ac6-3ce4990cce24/Red_clover_herbarium.jpg", "fileSize": 557238, "assetType": "image", "resource": "e7cd2cac2e5bfce2878a707377bf42d6", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/45/454581ee-d0f1-4eb3-9ac6-3ce4990cce24/Red_clover_herbarium.jpg" }, { "id": "c65a949c-5822-49bb-ad5d-647cd9820c57", "name": "Red clover", "classification": "content", "description": "This content provides information on the red clover.", "lastModified": "2017-06-27T14:49:36.389Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:36.389Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "clover", "purple", "luck", "pink" ], "type": "Plant", "categories": [ "Plant classification/Plantae/Angiosperms/Eudicots/Rosids/Fabales/Fabaceae/Faboideae/Trifolieae/Trifolium", "Plant habitats/Grassland/Meadow/Wet meadow" ] } ] } ~~~ #### **Specifying the fields to return** #### This example demonstrates the use of the "fl" parameter. It defines that only the "name" field and the "classification" field will be returned for each document matching the query. The number of returned documents is limited to 10 by default. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?q=tags:thistle&fl=name&fl=classification ~~~ ##### *Response:* ##### ~~~ { "numFound": 12, "documents": [ { "name": "Spiny_sowthistle.jpg", "classification": "asset" }, { "name": "Common_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Common_sowthistle.pdf", "classification": "asset" }, { "name": "Common_sowthistle.jpg", "classification": "asset" }, { "name": "Spiny_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Spiny_sowthistle.pdf", "classification": "asset" }, { "name": "Common sowthistle", "classification": "content" }, { "name": "Spiny sowthistle", "classification": "content" }, { "name": "Marsh thistle", "classification": "content" }, { "name": "Marsh_thistle.jpg", "classification": "asset" } ] } ~~~ #### **Limiting the number of results and returned fields** #### In this example, the maximum number of documents to include in the query result is limited to 5. By default, if you do not specify the "rows" parameter, the service returns a maximum of 10 documents. The "fl" parameter defines that only the "name" field and the "classification" field will be returned for each document matching the quey. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?q=tags:thistle&fl=name&fl=classification&rows=5 ~~~ ##### *Response:* ##### ~~~ { "numFound": 12, "documents": [ { "name": "Spiny_sowthistle.jpg", "classification": "asset" }, { "name": "Common_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Common_sowthistle.pdf", "classification": "asset" }, { "name": "Common_sowthistle.jpg", "classification": "asset" }, { "name": "Spiny_sowthistle_herbarium.jpg", "classification": "asset" } ] } ~~~ #### **Paging through the query result** #### In this example, the "rows" parameter is still set to 5 to limit the number of documents returned by the query. The "start" parameter defines an absolute offset of 3 in the complete sorted list of matches. Therefore, the result of the query includes documents 4 through 8 from a total of 12 documents that match the query. If an index modification (adding or removing) which affects the sequence of ordered documents matching a query occurs in between two requests from a client for subsequent pages of results then it is possible that these modifications can result in the same document being returned on multiple pages, or documents being "skipped" as the result set shrinks or grows. For more information about sorting and paging see the Solr documentation. The default value of the "start" parameter is 0. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?q=tags:thistle&fl=name&fl=classification&rows=5&start=3 ~~~ ##### *Response:* ##### ~~~ { "numFound": 12, "documents": [ { "name": "Common_sowthistle.pdf", "classification": "asset" }, { "name": "Spiny_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Spiny_sowthistle.pdf", "classification": "asset" }, { "name": "Common sowthistle", "classification": "content" }, { "name": "Spiny sowthistle", "classification": "content" } ] } ~~~ #### **Sorting the query result** #### In this example, the query contains the "sort" parameter to sort the query result by "name" in an ascending order. The response includes the first 5 documents from the sorted query result. If an index modification (such as adding or removing documents) which affects the sequence of ordered documents matching a query occurs in between two requests from a client for subsequent pages of results, then it is possible that these modifications can result in the same document being returned on multiple pages, or documents being "skipped" as the result set shrinks or grows. It's recommended to sort by unique field or their combination ex: sort=name asc, lastModified asc ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?q=tags:thistle&fl=name&fl=classification&rows=5&sort=name asc,lastModified asc ~~~ ##### *Response:* ##### ~~~ { "numFound": 12, "documents": [ { "name": "Common sowthistle", "classification": "content" }, { "name": "Common_sowthistle.jpg", "classification": "asset" }, { "name": "Common_sowthistle.pdf", "classification": "asset" }, { "name": "Common_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Marsh thistle", "classification": "content" } ] } ~~~ #### **Getting only the number of matching documents** #### This example demonstrates how you can limit the response to only the number of documents that match the query by adding the "rows" parameters with a value of 0. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?q=*:*&rows=0 ~~~ ##### *Response:* ##### ~~~ { "numFound": 182 } ~~~ #### **Using boolean operators in a query** #### This example demonstrates the use of a boolean operator to combine different conditions in the query. This particular query returns Watson Content Hub "content" that is tagged with "dandelion". The fields of matching documents that are included in the response are limited to "name", "classification", and "tags". ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?q=classification:content AND tags:dandelion&fl=name&fl=classification&fl=tags ~~~ ##### *Response:* ##### ~~~ { "numFound": 1, "documents": [ { "name": "Common dandelion", "classification": "content", "tags": [ "dandelion", "yellow", "tortoise" ] } ] } ~~~ #### **Getting the "document" field as JSON object** #### In this example, the query is extended by an additional "fl" parameter to also retrieve the "document" field. To return the value of that specific field as JSON object, the "[json]" qualifier is added. By default, the field value is returned as an escaped JSON string. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?q=classification:content AND tags:dandelion&fl=name&fl=classification&fl=tags&fl=document:[json] ~~~ ##### *Response:* ##### ~~~ { "numFound": 1, "documents": [ { "name": "Common dandelion", "classification": "content", "tags": [ "dandelion", "yellow", "tortoise" ], "document": { "id": "662c212c-e8f6-4dcc-b4fa-cddb76aac7c0", "name": "Common dandelion", "description": "This content provides information on the common dandelion.", "classification": "content", "typeId": "357e5d59-be20-4fe5-ba9e-31913f6fc229", "locale": "en", "lastModified": "2017-06-27T14:49:35.361Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:35.361Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "dandelion", "yellow", "tortoise" ], "status": "ready", "elements": { "source": { "elementType": "link", "linkURL": "https://en.wikipedia.org/wiki/Taraxacum_officinale", "linkText": "Wikipedia" }, "scientificClassification": { "elementType": "category", "categoryIds": [ "e7411413986ff741cb4495df45e4b7a1" ], "categories": [ "Plant classification/Plantae/Angiosperms/Eudicots/Asterids/Asterales/Asteraceae/Cichorioideae/Cichorieae/Taraxacum" ] }, "attachment": { "elementType": "file", "asset": { "id": "ba56e2b8-c7bf-4f45-b791-323f85fdfbc5", "resourceUri": "/delivery/v1/resources/623912367a4183a13fd53be2ad9d65e9", "fileSize": 485686, "fileName": "Common_dandelion.pdf", "mediaType": "application/pdf" }, "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/ba/ba56e2b8-c7bf-4f45-b791-323f85fdfbc5/Common_dandelion.pdf" }, "commonNames": { "elementType": "text", "value": "common dandelion,dandelion" }, "binomialName": { "elementType": "text", "value": "taraxacum officinale" }, "herbariumSpecimenDate": { "elementType": "datetime", "value": "1999-10-02T22:00:00Z" }, "photo": { "elementType": "image", "renditions": { "default": { "renditionId": "1d9c8fd6-5d82-477c-bf5c-08ef8bd3f9c8", "source": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg" } }, "asset": { "id": "16ae839a-5c79-4d83-bc80-14fa794c890f", "resourceUri": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91", "fileName": "Common_dandelion.jpg", "fileSize": 24800, "mediaType": "image/jpeg" }, "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg" }, "description": { "elementType": "text", "value": "Taraxacum officinale is a flowering herbaceous perennial plant of the family Asteraceae (Compositae).\n\nIt can be found growing in temperate regions of the world, in lawns, on roadsides, on disturbed banks and shores of water ways, and other areas with moist soils. T. officinale is considered a weed, especially in lawns and along roadsides, but it is sometimes used as a medical herb and in food preparation. Common dandelion is well known for its yellow flower heads that turn into round balls of silver tufted fruits that disperse in the wind called \"blowballs\" or \"clocks\" (in both British and American English).\n\nTaraxacum officinale grows from generally unbranched taproots and produces one to more than ten stems that are typically 5–40 cm (2.0–15.7 in) tall, but sometimes up to 70 cm (28 in) tall. The stems can be tinted purplish, they are upright or lax, and produce flower heads that are held as tall or taller than the foliage. The foliage may be upright-growing or horizontally spreading; the leaves have petioles that are either unwinged or narrowly winged. The stems can be glabrous or sparsely covered with short hairs. Plants have milky latex and the leaves are all basal; each flowering stem lacks bracts and has one single flower head. The yellow flower heads lack receptacle bracts and all the flowers, which are called florets, are ligulate and bisexual. In many lineages, fruits are mostly produced by apomixis, notwithstanding the flowers are visited by many types of insects.\n\nThe leaves are 5–45 cm (2.0–17.7 in) long and 1–10 cm (0.39–3.94 in) wide, and are oblanceolate, oblong, or obovate in shape, with the bases gradually narrowing to the petiole. The leaf margins are typically shallowly lobed to deeply lobed and often lacerate or toothed with sharp or dull teeth.\n\nThe calyculi (the cuplike bracts that hold the florets) are composed of 12 to 18 segments: each segment is reflexed and sometimes glaucous. The lanceolate shaped bractlets are in two series, with the apices acuminate in shape. The 14–25 mm (0.55–0.98 in) wide involucres are green to dark green or brownish-green, with the tips dark gray or purplish. The florets number 40 to over 100 per head, having corollas that are yellow or orange-yellow in color.\n\nThe fruits, called cypselae, range in color from olive-green or olive-brown to straw-colored to grayish, they are oblanceoloid in shape and 2–3 mm (0.079–0.118 in) long with slender beaks. The fruits have 4 to 12 ribs that have sharp edges. The silky pappi, which form the parachutes, are white to silver-white in color and around 6 mm wide. Plants typically have 24 or 40 pairs of chromosomes, while some have 16 or 32 pairs." }, "herbariumSpecimenLocality": { "elementType": "category", "categoryIds": [ "e7cd2cac2e5bfce2878a7073777b0e78" ], "categories": [ "Plant habitats/Grassland/Meadow/Wet meadow" ] }, "herbariumSpecimenPhoto": { "elementType": "image", "renditions": { "default": { "renditionId": "2be697cd-30df-4f1d-afc8-ac17fa0ab5a0", "source": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg" }, "medium": { "renditionId": "eb688f20-2fb0-414f-a6aa-8f6e0f8a61b3", "source": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530?resize=800px:1100px&crop=800:1100;0,0", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg?resize=800px%3A1100px&crop=800%3A1100%3B0%2C0" }, "large": { "renditionId": "112f0a63-72b0-4b39-b769-c7bdadcae542", "source": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530?resize=1200px:1650px&crop=1200:1650;0,0", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg?resize=1200px%3A1650px&crop=1200%3A1650%3B0%2C0" }, "small": { "renditionId": "4a06a904-64cd-4942-ae1b-1b15389e48e2", "source": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530?resize=400px:550px&crop=400:550;0,0", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg?resize=400px%3A550px&crop=400%3A550%3B0%2C0" } }, "asset": { "id": "852c1de4-661e-4a18-9ba8-bb49c65c50a6", "resourceUri": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530", "fileName": "Common_dandelion_herbarium.jpg", "fileSize": 695051, "mediaType": "image/jpeg" }, "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg" } }, "type": "Plant" } } ] } ~~~ #### **Getting documents including all available stored fields** #### In this example, the query matches all Watson Content Hub items of type "asset" that are tagged with "dandelion". The response includes the first document matching the query and provides all stored fields that are available for that document. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?q=classification:asset AND tags:dandelion&fl=*&rows=1&fl=document:[json] ~~~ ##### *Response:* ##### ~~~ { "numFound": 3, "documents": [ { "id": "16ae839a-5c79-4d83-bc80-14fa794c890f", "name": "Common_dandelion.jpg", "classification": "asset", "description": "This is an image of a common dandelion plant.", "lastModified": "2017-06-27T14:49:20.045Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:18.152Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "hawkweed", "common dandelion", "pale yellow color", "oxtongue", "dandelion", "cat's-ear", "plant", "weed", "yellow color", "herb" ], "mediaType": "image/jpeg", "path": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg", "fileSize": 24800, "location": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f", "locationPaths": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f", "assetType": "image", "resource": "14da685e6f1c2c67b26d5a0c80b2ed91", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg", "height": 300, "width": 300, "document": { "mediaType": "image/jpeg", "name": "Common_dandelion.jpg", "path": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg", "digest": "JK500obHI3/Rq9eoL+6/mg==", "usageRights": { "categories": [] }, "assetType": "image", "lastModified": "2017-06-27T14:49:20.045Z", "description": "This is an image of a common dandelion plant.", "tags": { "values": [ "classification:hawkweed", "classification:common dandelion", "classification:pale yellow color", "classification:oxtongue", "dandelion", "classification:cat's-ear", "classification:plant", "classification:weed", "classification:yellow color", "classification:herb" ], "declined": [], "analysis": "complete", "suggested": [ "classification:common dandelion", "classification:herb", "classification:plant", "classification:cat's-ear", "classification:weed", "classification:hawkweed", "classification:pale yellow color" ] }, "altText": "common dandelion", "categoryIds": [], "fileName": "Common_dandelion.jpg", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "cognitive": { "classifications": [ "common dandelion", "herb", "plant", "cat's-ear", "weed", "hawkweed", "pale yellow color" ], "faces": [], "colors": { "vibrant": "#d5b706", "muted": "#5c4c44", "darkVibrant": "#856706", "darkMuted": "#46522b" }, "status": "complete" }, "id": "16ae839a-5c79-4d83-bc80-14fa794c890f", "resource": "14da685e6f1c2c67b26d5a0c80b2ed91", "fileSize": 24800, "status": "ready", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "renditions": { "default": { "id": "r=14da685e6f1c2c67b26d5a0c80b2ed91&a=16ae839a-5c79-4d83-bc80-14fa794c890f", "source": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91" } }, "metadata": { "width": 300, "height": 300 }, "classification": "asset", "created": "2017-06-27T14:49:18.152Z", "links": { "media": { "href": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91.jpg" }, "thumbnail": { "href": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91?fit=inside%7C220:145" } }, "categories": [] }, "media": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91.jpg", "thumbnail": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91?fit=inside%7C220:145", "isManaged": true, "status": "ready", } ] } ~~~ #### **Searching only in a subset of all documents** #### This example demonstrates the use of the "fq" parameter to search only in the specific subset of all documents that are classified as "asset". The filter query is a means to limit the set of documents that can be returned by a query. Restricting the query to a subset of all documents can speed up complex queries, because the filter query is cached independently from the main query. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?fq=classification:asset&q=tags:dandelion&fl=name&fl=classification ~~~ ##### *Response:* ##### ~~~ { "numFound": 3, "documents": [ { "name": "Common_dandelion.pdf", "classification": "asset" }, { "name": "Common_dandelion_herbarium.jpg", "classification": "asset" }, { "name": "Common_dandelion.jpg", "classification": "asset" } ] } ~~~ #### **Getting documents based on the last modification date** #### This example demonstrates the use of the "fq" parameter to search only in the specific subset of all documents that were modified in the last 2 days. The filter query is a means to limit the set of documents that can be returned by a query. Restricting the query to a subset of all documents can speed up complex queries, because the filter query is cached independently from the main query. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?fq=lastModified:[NOW-2DAYS/DAY TO NOW]&q=tags:thistle&fl=lastModified&fl=name ~~~ ##### *Response:* ##### ~~~ { "numFound": 4, "documents": [ { "name": "Marsh thistle", "lastModified": "2017-07-03T08:37:10.966Z" }, { "name": "Marsh_thistle.jpg", "lastModified": "2017-07-03T08:38:50.870Z" }, { "name": "Marsh_thistle_herbarium.jpg", "lastModified": "2017-07-03T08:39:29.610Z" }, { "name": "Marsh_thistle.pdf", "lastModified": "2017-07-03T08:40:15.777Z" } ] } ~~~ #### **Getting documents with a specific field not set** #### In this example, all documents are filtered to retrieve only entries that have no data set for the field 'tags'. The query returns only the 5 most recently updated documents. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?q=*:*&fq=NOT tags:[* TO *]&sort=lastModified desc&rows=5&fl=name&fl=classification&fl=lastModified ~~~ ##### *Response:* ##### ~~~ { "numFound": 114, "documents": [ { "name": "Chelidonium", "classification": "category", "lastModified": "2017-06-27T15:00:24.342Z" }, { "name": "Taraxacum", "classification": "category", "lastModified": "2017-06-27T14:49:03.920Z" }, { "name": "Trifolium", "classification": "category", "lastModified": "2017-06-27T14:49:02.458Z" }, { "name": "Cirsium", "classification": "category", "lastModified": "2017-06-27T14:49:00.952Z" }, { "name": "Achillea", "classification": "category", "lastModified": "2017-06-27T14:48:59.416Z" } ] } ~~~ #### **Getting documents with a specific field not set in combination with an OR clause** #### In this example, all documents are filtered to retrieve only entries that were modified during the last 21 days or that have no data set for the field 'tags'. The query returns only the 5 most recently updated documents. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?q=*:*&fq=lastModified:[NOW-21DAYS TO NOW] OR (*:* NOT tags:[* TO *])&sort=lastModified desc&rows=5&fl=name&fl=classification&fl=lastModified ~~~ ##### *Response:* ##### ~~~ { "numFound": 115, "documents": [ { "name": "Marsh thistle", "classification": "content", "lastModified": "2017-07-03T08:37:10.966Z" }, { "name": "Chelidonium", "classification": "category", "lastModified": "2017-06-27T15:00:24.342Z" }, { "name": "Taraxacum", "classification": "category", "lastModified": "2017-06-27T14:49:03.920Z" }, { "name": "Trifolium", "classification": "category", "lastModified": "2017-06-27T14:49:02.458Z" }, { "name": "Cirsium", "classification": "category", "lastModified": "2017-06-27T14:49:00.952Z" } ] } ~~~ #### **Getting available facet terms** #### Faceted search organizes search results into categories based on terms from the indexed items. This can be useful, for example, to implement typeahead suggestions or filter functions. To enable faceting, add the "facet" parameter to the request and set its value to "true". Then use the "facet.field" parameter to specify each field to be treated as a facet. In this example, the response contains the facet terms that are available in the delivery collection for the fields "classification", "type", and "assetType". The request does not contain a query that matches any documents. Therefore, the "numFound" property from the response and the number following each facet term are 0. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType ~~~ ##### *Response:* ##### ~~~ { "numFound": 0, "facets": { "classification": [ "asset", 0, "category", 0, "content", 0, "taxonomy", 0 ], "type": [ "plant", 0 ], "assetType": [ "file", 0, "image", 0 ] } } ~~~ #### **Getting available facet terms that contain a specific substring** #### This example demonstrates the use of the "facet.contains" parameter to retrieve only facet terms that contain a specific character or character sequence. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType&facet.contains=nt ~~~ ##### *Response:* ##### ~~~ { "numFound": 0, "facets": { "classification": [ "content", 0 ], "type": [ "plant", 0 ], "assetType": [] } } ~~~ #### **Limiting the number of returned facet terms** #### This example uses the "facet.limit" parameter to obtain only the first facet term for each selected facet. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType&facet.limit=1 ~~~ ##### *Response:* ##### ~~~ { "numFound": 0, "facets": { "classification": [ "asset", 0 ], "type": [ "plant", 0 ], "assetType": [ "file", 0 ] } } ~~~ #### **Paging through the returned facet terms** #### In this example, the "facet.limit" parameter is still set to 1 to limit the number of facet terms in the response. The "facet.offset" parameter defines an offset of 1. Therefore, the response includes the second facet term for each facet provided there are more facet terms available. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType&facet.limit=1&facet.offset=1 ~~~ ##### *Response:* ##### ~~~ { "numFound": 0, "facets": { "classification": [ "category", 0 ], "type": [], "assetType": [ "image", 0 ] } } ~~~ #### **Getting facet ranges** #### This example demonstrates the use of range faceting by adding corresponding "facet.range" parameters to the request. Range faceting is supported on date and numeric fields that support range queries. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?facet=true&facet.range=created&facet.range.start=NOW/DAY-3DAYS&facet.range.end=NOW&facet.range.gap=%2B1DAY ~~~ ##### Response: ##### ~~~ { "numFound": 0, "facet_ranges": { "created": { "counts": [ "2017-07-03T00:00:00Z", 0, "2017-07-04T00:00:00Z", 0, "2017-07-05T00:00:00Z", 0, "2017-07-06T00:00:00Z", 0 ], "gap": "+1DAY", "start": "2017-07-03T00:00:00Z", "end": "2017-07-07T00:00:00Z" } } } ~~~ #### **Getting the facet term information for a query result** #### This example shows the combination of a query and faceting. The response contains information about the usage of the selected facet terms across all documents of the query result. Among the 32 documents that match the query there are: * 24 documents with the "classification" field value set to "asset" and 8 classified as "content" * 8 documents with the content "type" field value set to "plant" * 16 documents with the "assetType" field value set to "image" and 8 assets of type "file" ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?q=name:Common*&fl=name&fl=classification&facet=true&facet.field=classification&facet.field=type&facet.field=assetType&rows=5 ~~~ ##### *Response:* ##### ~~~ { "numFound": 32, "documents": [ { "name": "Common_daisy.jpg", "classification": "asset" }, { "name": "Common_reed_herbarium.jpg", "classification": "asset" }, { "name": "Common_yarrow.jpg", "classification": "asset" }, { "name": "Common_buttercup_herbarium.jpg", "classification": "asset" }, { "name": "Common_nettle.pdf", "classification": "asset" } ], "facets": { "classification": [ "asset", 24, "content", 8, "category", 0, "taxonomy", 0 ], "type": [ "plant", 8 ], "assetType": [ "image", 16, "file", 8 ] } } ~~~ #### **Using the Extended DisMax query parser** #### The Watson Content Hub delivery search service REST API includes an additional query parser that supports more parameters than the standard query parser used in the previous examples. In this example, the "defType" parameter tells the service to use the "edismax" query parser. The query that matches the term "content" or "asset" is performed on the query field "classification" that is specified using the "qf" parameter. The response includes a maximum of 1 document as per "rows" parameter. ##### *Request:* ##### ~~~ {baseURL}/delivery/v1/search?q=content OR asset&defType=edismax&qf=classification&rows=1 ~~~ ##### *Response:* ##### ~~~ { "numFound": 68, "documents": [ { "id": "5a5f65c0-c01f-438e-acf1-a707cb3a9bed", "name": "Common nettle", "classification": "content", "description": "This content provides information on the common nettle.", "lastModified": "2017-06-27T14:49:35.370Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:35.370Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "nettle", "brown", "green" ], "type": "Plant", "categories": [ "Plant habitats/Grassland/Meadow/Wet meadow", "Plant classification/Plantae/Angiosperms/Eudicots/Rosids/Rosales/Urticaceae/Urticoideae/Urticeae/Urtica" ] } ] } ~~~
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Search in the delivery collection](https://developer.goacoustic.com/acoustic-content/reference/get_mydelivery-v1-search.md): Performs a search query by passing all query parameters to Solr. Search results will contain unprotected and protected items. This route is restricted to authenticated users. The supported query parser for the "defType" parameter can be "edismax" or "lucene". The query parser name defined in "q" or "fq" parameter through "{! ...}" can have the value "join", "lucene", "edismax", or "geofilt". For more information about the query syntax and the available query parameters, see the Solr documentation. ### ***Description of the delivery collection schema*** ### The table below lists the **Name** of each field from the delivery collection. Additionally, it contains a **Description** of each field along with the following information: * **JSON Data Type:** This column specifies the data type of field values that Watson Content Hub returns in the result of a query. * **Solr Field Type:** This column specifies how Watson Content Hub stores values of the field in the delivery collection. * **boolean:** This field type is based on the Solr *BoolField* class. * **date:** This field type is based on the Solr *TrieDateField* class. * **int:** This field type is based on the Solr *TrieIntField* class. * **long:** This field type is based on the Solr *TrieLongField* class. * **location_rpt:** This field type is based on the Solr *LatLonPointSpatialField* class. * **path_hierarchical_index:** This field type is based on the Solr *TextField* class. It uses a hierarchical path tokenizer to index field values. * **string:** This field type is based on the Solr *StrField* class. * **string_ci:** This field type is based on the Solr *TextField* class. It is a case insensitive version of *string* field type. * **text_general:** This field type is based on the Solr *TextField* class. * **Indexed:** This column specifies whether you can use values of the field in a query to retrieve matching documents. * **Stored:** This column specifies whether you can retrieve the actual value of the field using a query. The fields ***highlighted*** in this column are included in the query result by default. To override that default field list, use the "fl" parameter in your query. | Name | Description | JSON Data Type | Solr Field Type | Indexed | Stored* | |-------------------------|-------------|----------------|-----------------|---------|---------| | aggregatedIds | For pages, this field contains the IDs that the page's appearance is made up of. This comprises the page's ID as well as the IDs of the page content item and it's directly referenced content items. Changes in one of those items will cause the page to be re-indexed. | array of strings | string_ci | true | true | | aggregatedContentIds | For pages, this field contains the content IDs that the page's appearance is made up of. This comprises the IDs of the page content item and it's directly referenced content items. Changes in one of those items will cause the page to be re-indexed. | array of strings | string_ci | true | true | | assetType | For assets, this field contains the asset type. The value that is returned can be "document", "file", "image", or "video". | string | string_ci | true | ***true*** | | boolean1 | For content, this field can contain boolean element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of booleans | boolean | true | true | | boolean2 | For content, this field can contain boolean element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of booleans | boolean | true | true | | categories | The list of all category selections for the asset or content. All category selection elements on content are merged into this property. | array of strings | path_hierarchical_index | true | ***true*** | | categoryLeaves | The list of all leaf category selection elements for the asset or content. | array of strings | string_ci | true | false | | classification | This field describes the kind of item. The value that is returned can be "asset", "category", "content" or "taxonomy". | string | string_ci | true | ***true*** | | created | The creation date of the item. | string | date | true | ***true*** | | creatorId | The UUID of the user that created the item. | string | string | true | ***true*** | | date1 | For content, this field can contain date element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of strings | date | true | true | | date2 | For content, this field can contain date element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of strings | date | true | true | | description | The description of the item. | string | text_general | true | ***true*** | | document | For assets and content, this field contains the full JSON document for the item. | string | string | false | true | | fileSize | For assets, this field contains the file size in bytes. | number | long | true | ***true*** | | generatedFiles | For content, this field contains the list of path values related to files that are generated by pre-rendering the item. | array of strings | string | true | true | | height | For images, this field contains the height. | number | int | true | true | | hideFromNavigation | For pages, this field specifies whether it should be hidden from navigation controls. | boolean | boolean | true | true | | id | The identifier of the item. For items of the same "classification", this identifier is unique. The combination of the "classification" and the "id" is unique across all items of the Watson Content Hub tenant. | string | string | true | ***true*** | | isManaged | For assets and content, this field specifies whether the content is managed or not managed and whether the asset is a managed asset or a so-called non-managed web asset. | boolean | boolean | true | false | | keywords | The list of keywords related to the item. | array of strings | string_ci | true | ***true*** | | kind | For pages, this field contains all kinds a page is assigned to. | array of strings | string_ci | true | true | | lastModified | The last modification date of the item. | string | date | true | ***true*** | | lastModifierId | The UUID of the user that last modified the item. | string | string | true | ***true*** | | locale | The language for which the item was created. | string | string_ci | true | true | | location | For assets, this field contains the folder path without the file name. This allows for efficient queries for sibling assets. | string | string_ci | true | false | | location1 | For content, this field contains an array of strings. Each string consists of the latitude and the longitude of location elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of strings | location_rpt | true | false | | locationPaths | For assets, this field contains all of the path segments. This allows for efficient queries that return assets in subfolders of the queried value. For example, the query *locationPaths:"/dxdam"* will return assets that are stored in the */dxdam* folder or any subfolder. | string | path_hierarchical_index | true | false | | locations | For content, this field contains an array of strings. Each string consists of the latitude and the longitude of a Location element of the content item. For example, this field contains ["48.666259, 9.039273", "53.418880, -6.416081"] for a content item with two Location elements. | array of strings | location_rpt | true | true | | media | For assets, this field contains the URL to the binary of the asset. It is relative to the API URL for your tenant. | string | string_ci | true | true | | mediaType | For assets, this field contains the media type. | string | string | true | ***true*** | | name | The name of the item. | string | string_ci | true | ***true*** | | number1 | For content, this field can contain number element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of numbers | double | true | true | | number2 | For content, this field can contain number element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of numbers | double | true | true | | parentId | For pages, this field contains the ID of the parent page. | string | string_ci | true | true | | path | For assets, this field contains the folder path including file name. | string | string_ci | true | ***true*** | | position | For pages, this field contains the position of the page relative to it's sibling pages. | number | int | true | true | | resource | For assets, this field contains the ID of the related resource. You can use this resource ID with the authoring and delivery resource service REST APIs. | string | string | true | ***true*** | | restricted | This field specifies whether the item is restricted. | boolean | boolean | true | false | | siteId | For pages, this field contains the ID of the site the page belongs to. | string | string_ci | true | true | | status | For assets and content, this field contains the state the item is in. The value of this field can be "ready" or "retired". | string | string_ci | true | true | | string1 | For content, this field can contain string element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of strings | string_ci | true | true | | string2 | For content, this field can contain string element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of strings | string_ci | true | true | | string3 | For content, this field can contain string element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of strings | string_ci | true | true | | string4 | For content, this field can contain string element values for elements mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | array of strings | string_ci | true | true | | sortableDate1 | For content, this field can contain a single date element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | string | date | true | true | | sortableDate2 | For content, this field can contain a single date element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | string | date | true | true | | sortableNumber1 | For content, this field can contain a single number element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | number | double | true | true | | sortableNumber2 | For content, this field can contain a single number element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | number | double | true | true | | sortableString1 | For content, this field can contain a single string element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | string | string_ci | true | true | | sortableString2 | For content, this field can contain a single string element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | string | string_ci | true | true | | sortableString3 | For content, this field can contain a single string element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | string | string_ci | true | true | | sortableString4 | For content, this field can contain a single string element value for an element mapped to this field. The mapping of elements to search fields is defined in the content type referenced by the content item. | string | string_ci | true | true | | tags | The list of tags assigned to the item. | array of strings | string_ci | true | ***true*** | | text | For content, this field is a collection of field names and text fragments that make up the item. It facilitates full-text search. | array of strings | text_general | true | false | | thumbnail | For assets, this field contains the URL to the thumbnail of the asset. It is relative to the API URL for your tenant. | string | string_ci | true | true | | type | For content, this field contains the name of the content type. | string | string_ci | true | ***true*** | | typeId | For content, this field contains the ID of the content type. | string | string_ci | true | true | | url | For assets, this field contains the server relative URL to the binary document of the asset. For pages, it contains the URL under which the page can be adressed in an SPA. | string | string | false | ***true*** | | width | For images, this field contains the width. | number | int | true | true | \* **Note:** Temporarily, the delivery collection might store field values even though the table above indicates otherwise. ### ***Search Query Examples*** ### #### **Using a wildcard in the search term** #### In this example, the request URL defines a query using the standard query syntax. The "name" field is specified as the query field. The search term contains a wildcard to match any name that starts with the word "Red", for example "Red clover" or "Red_clover.pdf". The "numFound" property from the response provides the number of documents that match the query. The value of the "documents" property contains the documents from the delivery collection selected by the query. Each document is returned with its stored fields as explained in the description of the delivery collection schema. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?q=name:Red* ~~~ ##### *Response:* ##### ~~~ { "numFound": 4, "documents": [ { "id": "53876d53-fbcf-45cf-8d53-f640c93f55c0", "name": "Red_clover.jpg", "classification": "asset", "description": "This is an image of a red clover plant.", "lastModified": "2017-06-27T14:49:12.160Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:09.197Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "red clover", "clover", "alpine clover", "pink color", "plant", "purple color", "herb" ], "mediaType": "image/jpeg", "path": "/dxdam/53/53876d53-fbcf-45cf-8d53-f640c93f55c0/Red_clover.jpg", "fileSize": 25513, "assetType": "image", "resource": "b110f3efdb6e1d305a88348b1caca710", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/53/53876d53-fbcf-45cf-8d53-f640c93f55c0/Red_clover.jpg" }, { "id": "7001cf29-b28b-4462-9b4a-827ab15eaff4", "name": "Red_clover.pdf", "classification": "asset", "description": "Description of the red clover.", "lastModified": "2017-06-27T14:49:14.409Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:13.130Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "Trifolium pratense", "US Department of Agriculture", "American Cancer Society", "Europe", "Clover", "Western Asia", "South America", "Africa" ], "mediaType": "application/pdf", "path": "/dxdam/70/7001cf29-b28b-4462-9b4a-827ab15eaff4/Red_clover.pdf", "fileSize": 331680, "assetType": "file", "resource": "14da685e6f1c2c67b26d5a0c80bc2be8", "keywords": [ "red clover", "Trifolium pratense", "red clover flowers", "red clover rust", "Red Clover Pollination", "Red Clover Tea", "South America" ], "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/70/7001cf29-b28b-4462-9b4a-827ab15eaff4/Red_clover.pdf" }, { "id": "454581ee-d0f1-4eb3-9ac6-3ce4990cce24", "name": "Red_clover_herbarium.jpg", "classification": "asset", "description": "This is an image of the red clover from an herbarium.", "lastModified": "2017-06-27T14:49:13.608Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:11.157Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "olive green color", "plant", "clover", "herbarium", "sage green color" ], "mediaType": "image/jpeg", "path": "/dxdam/45/454581ee-d0f1-4eb3-9ac6-3ce4990cce24/Red_clover_herbarium.jpg", "fileSize": 557238, "assetType": "image", "resource": "e7cd2cac2e5bfce2878a707377bf42d6", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/45/454581ee-d0f1-4eb3-9ac6-3ce4990cce24/Red_clover_herbarium.jpg" }, { "id": "c65a949c-5822-49bb-ad5d-647cd9820c57", "name": "Red clover", "classification": "content", "description": "This content provides information on the red clover.", "lastModified": "2017-06-27T14:49:36.389Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:36.389Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "clover", "purple", "luck", "pink" ], "type": "Plant", "categories": [ "Plant classification/Plantae/Angiosperms/Eudicots/Rosids/Fabales/Fabaceae/Faboideae/Trifolieae/Trifolium", "Plant habitats/Grassland/Meadow/Wet meadow" ] } ] } ~~~ #### **Specifying the fields to return** #### This example demonstrates the use of the "fl" parameter. It defines that only the "name" field and the "classification" field will be returned for each document matching the query. The number of returned documents is limited to 10 by default. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?q=tags:thistle&fl=name&fl=classification ~~~ ##### *Response:* ##### ~~~ { "numFound": 12, "documents": [ { "name": "Spiny_sowthistle.jpg", "classification": "asset" }, { "name": "Common_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Common_sowthistle.pdf", "classification": "asset" }, { "name": "Common_sowthistle.jpg", "classification": "asset" }, { "name": "Spiny_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Spiny_sowthistle.pdf", "classification": "asset" }, { "name": "Common sowthistle", "classification": "content" }, { "name": "Spiny sowthistle", "classification": "content" }, { "name": "Marsh thistle", "classification": "content" }, { "name": "Marsh_thistle.jpg", "classification": "asset" } ] } ~~~ #### **Limiting the number of results and returned fields** #### In this example, the maximum number of documents to include in the query result is limited to 5. By default, if you do not specify the "rows" parameter, the service returns a maximum of 10 documents. The "fl" parameter defines that only the "name" field and the "classification" field will be returned for each document matching the quey. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?q=tags:thistle&fl=name&fl=classification&rows=5 ~~~ ##### *Response:* ##### ~~~ { "numFound": 12, "documents": [ { "name": "Spiny_sowthistle.jpg", "classification": "asset" }, { "name": "Common_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Common_sowthistle.pdf", "classification": "asset" }, { "name": "Common_sowthistle.jpg", "classification": "asset" }, { "name": "Spiny_sowthistle_herbarium.jpg", "classification": "asset" } ] } ~~~ #### **Paging through the query result** #### In this example, the "rows" parameter is still set to 5 to limit the number of documents returned by the query. The "start" parameter defines an offset of 3. Therefore, the result of the query includes documents 4 through 8 from a total of 12 documents that match the query. The default value of the "start" parameter is 0. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?q=tags:thistle&fl=name&fl=classification&rows=5&start=3 ~~~ ##### *Response:* ##### ~~~ { "numFound": 12, "documents": [ { "name": "Common_sowthistle.pdf", "classification": "asset" }, { "name": "Spiny_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Spiny_sowthistle.pdf", "classification": "asset" }, { "name": "Common sowthistle", "classification": "content" }, { "name": "Spiny sowthistle", "classification": "content" } ] } ~~~ #### **Sorting the query result** #### In this example, the query contains the "sort" parameter to sort the query result by "name" and "lastModified" in an ascending order. The response includes the first 5 documents from the sorted query result. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?q=tags:thistle&fl=name&fl=classification&rows=5&sort=name asc, lastModified asc ~~~ ##### *Response:* ##### ~~~ { "numFound": 12, "documents": [ { "name": "Common sowthistle", "classification": "content" }, { "name": "Common_sowthistle.jpg", "classification": "asset" }, { "name": "Common_sowthistle.pdf", "classification": "asset" }, { "name": "Common_sowthistle_herbarium.jpg", "classification": "asset" }, { "name": "Marsh thistle", "classification": "content" } ] } ~~~ #### **Getting only the number of matching documents** #### This example demonstrates how you can limit the response to only the number of documents that match the query by adding the "rows" parameters with a value of 0. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?q=*:*&rows=0 ~~~ ##### *Response:* ##### ~~~ { "numFound": 182 } ~~~ #### **Using boolean operators in a query** #### This example demonstrates the use of a boolean operator to combine different conditions in the query. This particular query returns Watson Content Hub "content" that is tagged with "dandelion". The fields of matching documents that are included in the response are limited to "name", "classification", and "tags". ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?q=classification:content AND tags:dandelion&fl=name&fl=classification&fl=tags ~~~ ##### *Response:* ##### ~~~ { "numFound": 1, "documents": [ { "name": "Common dandelion", "classification": "content", "tags": [ "dandelion", "yellow", "tortoise" ] } ] } ~~~ #### **Getting the "document" field as JSON object** #### In this example, the query is extended by an additional "fl" parameter to also retrieve the "document" field. To return the value of that specific field as JSON object, the "[json]" qualifier is added. By default, the field value is returned as an escaped JSON string. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?q=classification:content AND tags:dandelion&fl=name&fl=classification&fl=tags&fl=document:[json] ~~~ ##### *Response:* ##### ~~~ { "numFound": 1, "documents": [ { "name": "Common dandelion", "classification": "content", "tags": [ "dandelion", "yellow", "tortoise" ], "document": { "id": "662c212c-e8f6-4dcc-b4fa-cddb76aac7c0", "name": "Common dandelion", "description": "This content provides information on the common dandelion.", "classification": "content", "typeId": "357e5d59-be20-4fe5-ba9e-31913f6fc229", "locale": "en", "lastModified": "2017-06-27T14:49:35.361Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:35.361Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "dandelion", "yellow", "tortoise" ], "status": "ready", "elements": { "source": { "elementType": "link", "linkURL": "https://en.wikipedia.org/wiki/Taraxacum_officinale", "linkText": "Wikipedia" }, "scientificClassification": { "elementType": "category", "categoryIds": [ "e7411413986ff741cb4495df45e4b7a1" ], "categories": [ "Plant classification/Plantae/Angiosperms/Eudicots/Asterids/Asterales/Asteraceae/Cichorioideae/Cichorieae/Taraxacum" ] }, "attachment": { "elementType": "file", "asset": { "id": "ba56e2b8-c7bf-4f45-b791-323f85fdfbc5", "resourceUri": "/delivery/v1/resources/623912367a4183a13fd53be2ad9d65e9", "fileSize": 485686, "fileName": "Common_dandelion.pdf", "mediaType": "application/pdf" }, "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/ba/ba56e2b8-c7bf-4f45-b791-323f85fdfbc5/Common_dandelion.pdf" }, "commonNames": { "elementType": "text", "value": "common dandelion,dandelion" }, "binomialName": { "elementType": "text", "value": "taraxacum officinale" }, "herbariumSpecimenDate": { "elementType": "datetime", "value": "1999-10-02T22:00:00Z" }, "photo": { "elementType": "image", "renditions": { "default": { "renditionId": "1d9c8fd6-5d82-477c-bf5c-08ef8bd3f9c8", "source": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg" } }, "asset": { "id": "16ae839a-5c79-4d83-bc80-14fa794c890f", "resourceUri": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91", "fileName": "Common_dandelion.jpg", "fileSize": 24800, "mediaType": "image/jpeg" }, "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg" }, "description": { "elementType": "text", "value": "Taraxacum officinale is a flowering herbaceous perennial plant of the family Asteraceae (Compositae).\n\nIt can be found growing in temperate regions of the world, in lawns, on roadsides, on disturbed banks and shores of water ways, and other areas with moist soils. T. officinale is considered a weed, especially in lawns and along roadsides, but it is sometimes used as a medical herb and in food preparation. Common dandelion is well known for its yellow flower heads that turn into round balls of silver tufted fruits that disperse in the wind called \"blowballs\" or \"clocks\" (in both British and American English).\n\nTaraxacum officinale grows from generally unbranched taproots and produces one to more than ten stems that are typically 5–40 cm (2.0–15.7 in) tall, but sometimes up to 70 cm (28 in) tall. The stems can be tinted purplish, they are upright or lax, and produce flower heads that are held as tall or taller than the foliage. The foliage may be upright-growing or horizontally spreading; the leaves have petioles that are either unwinged or narrowly winged. The stems can be glabrous or sparsely covered with short hairs. Plants have milky latex and the leaves are all basal; each flowering stem lacks bracts and has one single flower head. The yellow flower heads lack receptacle bracts and all the flowers, which are called florets, are ligulate and bisexual. In many lineages, fruits are mostly produced by apomixis, notwithstanding the flowers are visited by many types of insects.\n\nThe leaves are 5–45 cm (2.0–17.7 in) long and 1–10 cm (0.39–3.94 in) wide, and are oblanceolate, oblong, or obovate in shape, with the bases gradually narrowing to the petiole. The leaf margins are typically shallowly lobed to deeply lobed and often lacerate or toothed with sharp or dull teeth.\n\nThe calyculi (the cuplike bracts that hold the florets) are composed of 12 to 18 segments: each segment is reflexed and sometimes glaucous. The lanceolate shaped bractlets are in two series, with the apices acuminate in shape. The 14–25 mm (0.55–0.98 in) wide involucres are green to dark green or brownish-green, with the tips dark gray or purplish. The florets number 40 to over 100 per head, having corollas that are yellow or orange-yellow in color.\n\nThe fruits, called cypselae, range in color from olive-green or olive-brown to straw-colored to grayish, they are oblanceoloid in shape and 2–3 mm (0.079–0.118 in) long with slender beaks. The fruits have 4 to 12 ribs that have sharp edges. The silky pappi, which form the parachutes, are white to silver-white in color and around 6 mm wide. Plants typically have 24 or 40 pairs of chromosomes, while some have 16 or 32 pairs." }, "herbariumSpecimenLocality": { "elementType": "category", "categoryIds": [ "e7cd2cac2e5bfce2878a7073777b0e78" ], "categories": [ "Plant habitats/Grassland/Meadow/Wet meadow" ] }, "herbariumSpecimenPhoto": { "elementType": "image", "renditions": { "default": { "renditionId": "2be697cd-30df-4f1d-afc8-ac17fa0ab5a0", "source": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg" }, "medium": { "renditionId": "eb688f20-2fb0-414f-a6aa-8f6e0f8a61b3", "source": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530?resize=800px:1100px&crop=800:1100;0,0", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg?resize=800px%3A1100px&crop=800%3A1100%3B0%2C0" }, "large": { "renditionId": "112f0a63-72b0-4b39-b769-c7bdadcae542", "source": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530?resize=1200px:1650px&crop=1200:1650;0,0", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg?resize=1200px%3A1650px&crop=1200%3A1650%3B0%2C0" }, "small": { "renditionId": "4a06a904-64cd-4942-ae1b-1b15389e48e2", "source": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530?resize=400px:550px&crop=400:550;0,0", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg?resize=400px%3A550px&crop=400%3A550%3B0%2C0" } }, "asset": { "id": "852c1de4-661e-4a18-9ba8-bb49c65c50a6", "resourceUri": "/delivery/v1/resources/b110f3efdb6e1d305a88348b1ca4d530", "fileName": "Common_dandelion_herbarium.jpg", "fileSize": 695051, "mediaType": "image/jpeg" }, "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/85/852c1de4-661e-4a18-9ba8-bb49c65c50a6/Common_dandelion_herbarium.jpg" } }, "type": "Plant" } } ] } ~~~ #### **Getting documents including all available stored fields** #### In this example, the query matches all Watson Content Hub items of type "asset" that are tagged with "dandelion". The response includes the first document matching the query and provides all stored fields that are available for that document. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?q=classification:asset AND tags:dandelion&fl=*&rows=1&fl=document:[json] ~~~ ##### *Response:* ##### ~~~ { "numFound": 3, "documents": [ { "id": "16ae839a-5c79-4d83-bc80-14fa794c890f", "name": "Common_dandelion.jpg", "classification": "asset", "description": "This is an image of a common dandelion plant.", "lastModified": "2017-06-27T14:49:20.045Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:18.152Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "hawkweed", "common dandelion", "pale yellow color", "oxtongue", "dandelion", "cat's-ear", "plant", "weed", "yellow color", "herb" ], "mediaType": "image/jpeg", "path": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg", "fileSize": 24800, "location": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f", "locationPaths": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f", "assetType": "image", "resource": "14da685e6f1c2c67b26d5a0c80b2ed91", "url": "/2a2d174a-0c35-495f-ba3a-e881dc71197c/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg", "height": 300, "width": 300, "document": { "mediaType": "image/jpeg", "name": "Common_dandelion.jpg", "path": "/dxdam/16/16ae839a-5c79-4d83-bc80-14fa794c890f/Common_dandelion.jpg", "digest": "JK500obHI3/Rq9eoL+6/mg==", "usageRights": { "categories": [] }, "assetType": "image", "lastModified": "2017-06-27T14:49:20.045Z", "description": "This is an image of a common dandelion plant.", "tags": { "values": [ "classification:hawkweed", "classification:common dandelion", "classification:pale yellow color", "classification:oxtongue", "dandelion", "classification:cat's-ear", "classification:plant", "classification:weed", "classification:yellow color", "classification:herb" ], "declined": [], "analysis": "complete", "suggested": [ "classification:common dandelion", "classification:herb", "classification:plant", "classification:cat's-ear", "classification:weed", "classification:hawkweed", "classification:pale yellow color" ] }, "altText": "common dandelion", "categoryIds": [], "fileName": "Common_dandelion.jpg", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "cognitive": { "classifications": [ "common dandelion", "herb", "plant", "cat's-ear", "weed", "hawkweed", "pale yellow color" ], "faces": [], "colors": { "vibrant": "#d5b706", "muted": "#5c4c44", "darkVibrant": "#856706", "darkMuted": "#46522b" }, "status": "complete" }, "id": "16ae839a-5c79-4d83-bc80-14fa794c890f", "resource": "14da685e6f1c2c67b26d5a0c80b2ed91", "fileSize": 24800, "status": "ready", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "renditions": { "default": { "id": "r=14da685e6f1c2c67b26d5a0c80b2ed91&a=16ae839a-5c79-4d83-bc80-14fa794c890f", "source": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91" } }, "metadata": { "width": 300, "height": 300 }, "classification": "asset", "created": "2017-06-27T14:49:18.152Z", "links": { "media": { "href": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91.jpg" }, "thumbnail": { "href": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91?fit=inside%7C220:145" } }, "categories": [] }, "media": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91.jpg", "thumbnail": "/delivery/v1/resources/14da685e6f1c2c67b26d5a0c80b2ed91?fit=inside%7C220:145", "isManaged": true, "status": "ready", } ] } ~~~ #### **Searching only in a subset of all documents** #### This example demonstrates the use of the "fq" parameter to search only in the specific subset of all documents that are classified as "asset". The filter query is a means to limit the set of documents that can be returned by a query. Restricting the query to a subset of all documents can speed up complex queries, because the filter query is cached independently from the main query. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?fq=classification:asset&q=tags:dandelion&fl=name&fl=classification ~~~ ##### *Response:* ##### ~~~ { "numFound": 3, "documents": [ { "name": "Common_dandelion.pdf", "classification": "asset" }, { "name": "Common_dandelion_herbarium.jpg", "classification": "asset" }, { "name": "Common_dandelion.jpg", "classification": "asset" } ] } ~~~ #### **Getting documents based on the last modification date** #### This example demonstrates the use of the "fq" parameter to search only in the specific subset of all documents that were modified in the last 2 days. The filter query is a means to limit the set of documents that can be returned by a query. Restricting the query to a subset of all documents can speed up complex queries, because the filter query is cached independently from the main query. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?fq=lastModified:[NOW-2DAYS/DAY TO NOW]&q=tags:thistle&fl=lastModified&fl=name ~~~ ##### *Response:* ##### ~~~ { "numFound": 4, "documents": [ { "name": "Marsh thistle", "lastModified": "2017-07-03T08:37:10.966Z" }, { "name": "Marsh_thistle.jpg", "lastModified": "2017-07-03T08:38:50.870Z" }, { "name": "Marsh_thistle_herbarium.jpg", "lastModified": "2017-07-03T08:39:29.610Z" }, { "name": "Marsh_thistle.pdf", "lastModified": "2017-07-03T08:40:15.777Z" } ] } ~~~ #### **Getting documents with a specific field not set** #### In this example, all documents are filtered to retrieve only entries that have no data set for the field 'tags'. The query returns only the 5 most recently updated documents. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?q=*:*&fq=NOT tags:[* TO *]&sort=lastModified desc&rows=5&fl=name&fl=classification&fl=lastModified ~~~ ##### *Response:* ##### ~~~ { "numFound": 114, "documents": [ { "name": "Chelidonium", "classification": "category", "lastModified": "2017-06-27T15:00:24.342Z" }, { "name": "Taraxacum", "classification": "category", "lastModified": "2017-06-27T14:49:03.920Z" }, { "name": "Trifolium", "classification": "category", "lastModified": "2017-06-27T14:49:02.458Z" }, { "name": "Cirsium", "classification": "category", "lastModified": "2017-06-27T14:49:00.952Z" }, { "name": "Achillea", "classification": "category", "lastModified": "2017-06-27T14:48:59.416Z" } ] } ~~~ #### **Getting documents with a specific field not set in combination with an OR clause** #### In this example, all documents are filtered to retrieve only entries that were modified during the last 21 days or that have no data set for the field 'tags'. The query returns only the 5 most recently updated documents. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?q=*:*&fq=lastModified:[NOW-21DAYS TO NOW] OR (*:* NOT tags:[* TO *])&sort=lastModified desc&rows=5&fl=name&fl=classification&fl=lastModified ~~~ ##### *Response:* ##### ~~~ { "numFound": 115, "documents": [ { "name": "Marsh thistle", "classification": "content", "lastModified": "2017-07-03T08:37:10.966Z" }, { "name": "Chelidonium", "classification": "category", "lastModified": "2017-06-27T15:00:24.342Z" }, { "name": "Taraxacum", "classification": "category", "lastModified": "2017-06-27T14:49:03.920Z" }, { "name": "Trifolium", "classification": "category", "lastModified": "2017-06-27T14:49:02.458Z" }, { "name": "Cirsium", "classification": "category", "lastModified": "2017-06-27T14:49:00.952Z" } ] } ~~~ #### **Getting available facet terms** #### Faceted search organizes search results into categories based on terms from the indexed items. This can be useful, for example, to implement typeahead suggestions or filter functions. To enable faceting, add the "facet" parameter to the request and set its value to "true". Then use the "facet.field" parameter to specify each field to be treated as a facet. In this example, the response contains the facet terms that are available in the delivery collection for the fields "classification", "type", and "assetType". The request does not contain a query that matches any documents. Therefore, the "numFound" property from the response and the number following each facet term are 0. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType ~~~ ##### *Response:* ##### ~~~ { "numFound": 0, "facets": { "classification": [ "asset", 0, "category", 0, "content", 0, "taxonomy", 0 ], "type": [ "plant", 0 ], "assetType": [ "file", 0, "image", 0 ] } } ~~~ #### **Getting available facet terms that contain a specific substring** #### This example demonstrates the use of the "facet.contains" parameter to retrieve only facet terms that contain a specific character or character sequence. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType&facet.contains=nt ~~~ ##### *Response:* ##### ~~~ { "numFound": 0, "facets": { "classification": [ "content", 0 ], "type": [ "plant", 0 ], "assetType": [] } } ~~~ #### **Limiting the number of returned facet terms** #### This example uses the "facet.limit" parameter to obtain only the first facet term for each selected facet. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType&facet.limit=1 ~~~ ##### *Response:* ##### ~~~ { "numFound": 0, "facets": { "classification": [ "asset", 0 ], "type": [ "plant", 0 ], "assetType": [ "file", 0 ] } } ~~~ #### **Paging through the returned facet terms** #### In this example, the "facet.limit" parameter is still set to 1 to limit the number of facet terms in the response. The "facet.offset" parameter defines an offset of 1. Therefore, the response includes the second facet term for each facet provided there are more facet terms available. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?facet=true&facet.field=classification&facet.field=type&facet.field=assetType&facet.limit=1&facet.offset=1 ~~~ ##### *Response:* ##### ~~~ { "numFound": 0, "facets": { "classification": [ "category", 0 ], "type": [], "assetType": [ "image", 0 ] } } ~~~ #### **Getting facet ranges** #### This example demonstrates the use of range faceting by adding corresponding "facet.range" parameters to the request. Range faceting is supported on date and numeric fields that support range queries. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?facet=true&facet.range=created&facet.range.start=NOW/DAY-3DAYS&facet.range.end=NOW&facet.range.gap=%2B1DAY ~~~ ##### Response: ##### ~~~ { "numFound": 0, "facet_ranges": { "created": { "counts": [ "2017-07-03T00:00:00Z", 0, "2017-07-04T00:00:00Z", 0, "2017-07-05T00:00:00Z", 0, "2017-07-06T00:00:00Z", 0 ], "gap": "+1DAY", "start": "2017-07-03T00:00:00Z", "end": "2017-07-07T00:00:00Z" } } } ~~~ #### **Getting the facet term information for a query result** #### This example shows the combination of a query and faceting. The response contains information about the usage of the selected facet terms across all documents of the query result. Among the 32 documents that match the query there are: * 24 documents with the "classification" field value set to "asset" and 8 classified as "content" * 8 documents with the content "type" field value set to "plant" * 16 documents with the "assetType" field value set to "image" and 8 assets of type "file" ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?q=name:Common*&fl=name&fl=classification&facet=true&facet.field=classification&facet.field=type&facet.field=assetType&rows=5 ~~~ ##### *Response:* ##### ~~~ { "numFound": 32, "documents": [ { "name": "Common_daisy.jpg", "classification": "asset" }, { "name": "Common_reed_herbarium.jpg", "classification": "asset" }, { "name": "Common_yarrow.jpg", "classification": "asset" }, { "name": "Common_buttercup_herbarium.jpg", "classification": "asset" }, { "name": "Common_nettle.pdf", "classification": "asset" } ], "facets": { "classification": [ "asset", 24, "content", 8, "category", 0, "taxonomy", 0 ], "type": [ "plant", 8 ], "assetType": [ "image", 16, "file", 8 ] } } ~~~ #### **Using the Extended DisMax query parser** #### The Watson Content Hub delivery search service REST API includes an additional query parser that supports more parameters than the standard query parser used in the previous examples. In this example, the "defType" parameter tells the service to use the "edismax" query parser. The query that matches the term "content" or "asset" is performed on the query field "classification" that is specified using the "qf" parameter. The response includes a maximum of 1 document as per "rows" parameter. ##### *Request:* ##### ~~~ {baseURL}/mydelivery/v1/search?q=content OR asset&defType=edismax&qf=classification&rows=1 ~~~ ##### *Response:* ##### ~~~ { "numFound": 68, "documents": [ { "id": "5a5f65c0-c01f-438e-acf1-a707cb3a9bed", "name": "Common nettle", "classification": "content", "description": "This content provides information on the common nettle.", "lastModified": "2017-06-27T14:49:35.370Z", "lastModifierId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "created": "2017-06-27T14:49:35.370Z", "creatorId": "7129fa28-0d25-4162-8700-cbc5c294dacc", "tags": [ "nettle", "brown", "green" ], "type": "Plant", "categories": [ "Plant habitats/Grassland/Meadow/Wet meadow", "Plant classification/Plantae/Angiosperms/Eudicots/Rosids/Rosales/Urticaceae/Urticoideae/Urticeae/Urtica" ] } ] } ~~~
User roles: admin, manager, editor, viewer, authenticatedVisitor
- [Get the site descriptor of a public site](https://developer.goacoustic.com/acoustic-content/reference/get_delivery-v1-sites-siteid.md): Returns the site descriptor of the site specified by *siteId*.
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Get the site descriptor of a public or protected site.](https://developer.goacoustic.com/acoustic-content/reference/get_mydelivery-v1-sites-siteid.md): Returns the site descriptor of the site specified by *siteId*.
User roles: admin, manager, editor, viewer, authenticatedVisitor
- [Get the site descriptor of a public site](https://developer.goacoustic.com/acoustic-content/reference/get_delivery-v2-sites-siteid.md): Returns the site descriptor of the site specified by *siteId*.
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Get the site descriptor of a public or protected site.](https://developer.goacoustic.com/acoustic-content/reference/get_mydelivery-v2-sites-siteid.md): Returns the site descriptor of the site specified by *siteId*.
User roles: admin, manager, editor, viewer, authenticatedVisitor
- [Get the descriptor of a public page from a site.](https://developer.goacoustic.com/acoustic-content/reference/get_delivery-v1-sites-siteid-pages-pageid.md): Returns the descriptor of the page item specified by *pageId*. The page is contained in a site that is contained in *siteId*
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Get the descriptor of a public or protected page from a site.](https://developer.goacoustic.com/acoustic-content/reference/get_mydelivery-v1-sites-siteid-pages-pageid.md): Returns the descriptor of the page item specified by *pageId*. The page is contained in a site that is contained in *siteId*
User roles: admin, manager, editor, viewer, authenticatedVisitor
- [Get all public child pages of a specified parent page](https://developer.goacoustic.com/acoustic-content/reference/get_delivery-v1-sites-siteid-pages-by-parent-parentpageid.md): Returns the descriptors of all public child pages which are direct children of the parent page that is specified by *parentPageId*. The page is a member of the site that is specified in *siteId*. If the value of *parentPageId* is ***@top***, then the descriptors of the top-level pages are returned.
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Get all public or protected child pages of a specified parent page](https://developer.goacoustic.com/acoustic-content/reference/get_mydelivery-v1-sites-siteid-pages-by-parent-parentpageid.md): Returns the descriptors of all public or protected child pages which are direct children of the parent page that is specified by *parentPageId*. The page is a member of the site that is specified in *siteId*. If the value of *parentPageId* is ***@top***, then the descriptors of the top-level pages are returned.
User roles: admin, manager, editor, viewer, authenticatedVisitor
- [Retrieve a tenant](https://developer.goacoustic.com/acoustic-content/reference/get_registry-v1-currenttenant.md): ##### Example request using curl `curl -X GET {api-url}/registry/v1/currenttenant` If the user is not logged in then the /definitions/TenantAnonymous is returned
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Update a tenant](https://developer.goacoustic.com/acoustic-content/reference/put_registry-v1-currenttenant.md): ##### Example request using curl `curl -X PUT -d '{"_id":"85b4686b-8614-475f-8933-144d42f84521","locale":"de", "name":"sample_tenant"}' {api-url}/registry/v1/currenttenant`
User roles: admin
- [Remove tenant and auth cookie.](https://developer.goacoustic.com/acoustic-content/reference/get_login-v1-removecookies.md): Endpoint to receive a set-cookie cleaning the authentication and tenant cookies for the actual domain.
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Userid and password login using GET operation](https://developer.goacoustic.com/acoustic-content/reference/get_login-v1-basicauth.md): Performs basic authentication using Acoustic ID credentials. The API responds with authentication token (set in the cookie) and tenant information in the response header x-ibm-dx-tenant-id/x-cms-tenant-id. If no tenant for the user is found, the authentication fails presenting a HTTP404 error. You can also use API key generated by MyAcoustic page, in which case username is AcousticAPIKey while generating the Base64 encoded Authorization header.
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Userid and password login using POST operation](https://developer.goacoustic.com/acoustic-content/reference/post_login-v1-basicauth.md): Performs basic authentication using Acoustic ID credentials. The API responds with authentication token (set in the cookie) and tenant information in the response header x-ibm-dx-tenant-id/x-cms-tenant-id. If no tenant for the user is found, the authentication fails presenting a HTTP404 error. You can also use API key generated by MyAcoustic page, in which case username is AcousticAPIKey while generating the Base64 encoded Authorization header.
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Find the current user](https://developer.goacoustic.com/acoustic-content/reference/get_user-profile-v1-users-currentuser.md): Returns the current user
User roles: admin, manager, editor, viewer, authenticatedVisitor, anonymous
- [Find all users.](https://developer.goacoustic.com/acoustic-content/reference/get_user-profile-v1-users.md): Returns an array containing all users matching the query.
User roles: admin
- [Add a new user.](https://developer.goacoustic.com/acoustic-content/reference/post_user-profile-v1-users.md): Adds a new user and returns the user object.
User roles: admin
- [Find user by ID.](https://developer.goacoustic.com/acoustic-content/reference/get_user-profile-v1-users-id.md): Returns a single user.
User roles: admin
- [Update an existing user.](https://developer.goacoustic.com/acoustic-content/reference/put_user-profile-v1-users-id.md): Updates an existing user and returns the updated user object.
User roles: admin
- [Delete an existing user.](https://developer.goacoustic.com/acoustic-content/reference/delete_user-profile-v1-users-id.md): Deletes an existing user.
User roles: admin
- [Retrieves the webhook profile for the current tenant](https://developer.goacoustic.com/acoustic-content/reference/get_webhook-v1-profile.md): Use the /profile end-point to retrieve the webhook profile from the database.
User roles: admin
- [Creates or updates the webhook profile for the current tenant](https://developer.goacoustic.com/acoustic-content/reference/put_webhook-v1-profile.md): Use the /profile end-point to save the webhook profile within the database. This will overwrite any existing webhook profile. ### Sample Webhook Payload (sent to specified URLs) ``` { "event":"created" "timestamp": "2018-09-03T01:48:15.921Z" "doc" : { ... } } ```
User roles: admin
- [Deletes the webhook profile for the current tenant.](https://developer.goacoustic.com/acoustic-content/reference/delete_webhook-v1-profile.md): Use the /profile endpoint to delete the webhook profile from the database.
User roles: admin
- [Create a job](https://developer.goacoustic.com/acoustic-content/reference/post_publishing-v1-jobs.md): Use the /jobs endpoint to create a job. The job starts automatically and runs asynchronously. Use the /jobs/current-job/status to retrieve the details about the current job status.
User roles: admin, manager
- [Retrieve an existing job](https://developer.goacoustic.com/acoustic-content/reference/get_publishing-v1-jobs-current-job.md): Use the /jobs/current-job endpoint to retrieve current-job from the database.
User roles: admin, manager, editor
- [Retrieve the status of current-job](https://developer.goacoustic.com/acoustic-content/reference/get_publishing-v1-jobs-current-job-status.md): Use the /jobs/current-job/status endpoint to retrieve the status information for the current-job.
User roles: admin, manager, editor
- [Get the default site revision](https://developer.goacoustic.com/acoustic-content/reference/get_publishing-v1-site-revisions-default.md): Use the /site-revisions/default endpoint to retrieve the default site revision
User roles: admin, manager, editor
- [Update the default site revision](https://developer.goacoustic.com/acoustic-content/reference/put_publishing-v1-site-revisions-default.md): Use the /site-revisions/default endpoint to update the values of properties 'autoPublishEnabled', 'name' and 'description' by replacing them with the ones in request body. Please note: Modifications to the 'autoPublishEnabled' flag are not picked up by WCH immediately but with a time lag of up to 30 seconds
User roles: admin, manager
# Personalization Documentation
> Personalization enables marketers to deliver optimized and tailored content for each visitor in real-time, based on the visitor’s behavior and contextual data.
## Guides
- [Overview](https://developer.goacoustic.com/acoustic-personalization/docs/overview.md)
- [What's new](https://developer.goacoustic.com/acoustic-personalization/docs/whats-new.md)
- [Quick start for Personalization](https://developer.goacoustic.com/acoustic-personalization/docs/quick-start-guide-for-personalization.md): Set up personalization for websites built from Multi-Page or Single-Page Application
- [Setting up Personalization](https://developer.goacoustic.com/acoustic-personalization/docs/personalization-developer-workflow.md)
- [Exchange - Connect user data with Personalization](https://developer.goacoustic.com/acoustic-personalization/docs/exchange-connect-customer-data-with-personalization.md)
- [Analytics library - Collect and integrate behavioral data](https://developer.goacoustic.com/acoustic-personalization/docs/analytics-library-collect-and-integrate-behavioral-data.md)
- [Configure GTM - Add personalization tags](https://developer.goacoustic.com/acoustic-personalization/docs/configure-gtm-add-personalization-tags.md)
- [Configure DDX with Personalization](https://developer.goacoustic.com/acoustic-personalization/docs/configure-ddx-with-personalization-1.md)
- [Library overview](https://developer.goacoustic.com/acoustic-personalization/docs/library-overview.md)
- [Configure library](https://developer.goacoustic.com/acoustic-personalization/docs/configure-library.md)
- [Configure zones on your channel](https://developer.goacoustic.com/acoustic-personalization/docs/configure-zones-on-your-channel.md)
- [Create your product catalog](https://developer.goacoustic.com/acoustic-personalization/docs/product-catalog-specification.md)
- [Upload product catalog](https://developer.goacoustic.com/acoustic-personalization/docs/product-catalog-upload.md)
- [Configure product recommendations](https://developer.goacoustic.com/acoustic-personalization/docs/configure-product-recommendations.md)
- [Capture click events](https://developer.goacoustic.com/acoustic-personalization/docs/capture-click-events-1.md)
- [Configure geolocation](https://developer.goacoustic.com/acoustic-personalization/docs/configure-geolocation.md)
- [Display a recommendation title for the zone](https://developer.goacoustic.com/acoustic-personalization/docs/display-title-for-recommendation-zone.md)
- [Configure content management system](https://developer.goacoustic.com/acoustic-personalization/docs/configure-content-management-system.md)
- [Configure custom events](https://developer.goacoustic.com/acoustic-personalization/docs/configure-custom-events.md)
- [Add custom attributes - GTM](https://developer.goacoustic.com/acoustic-personalization/docs/add-custom-attributes.md)
- [Configure CartPurchaseItem events – AA](https://developer.goacoustic.com/acoustic-personalization/docs/configure-cartpurchaseitem-events.md)
- [Content rendering – Display the personalized content](https://developer.goacoustic.com/acoustic-personalization/docs/content-rendering-display-the-personalized-content.md)
- [Content rendering examples based on content types](https://developer.goacoustic.com/acoustic-personalization/docs/content-rendering-examples-based-on-content-types.md)
- [Glossary](https://developer.goacoustic.com/acoustic-personalization/docs/glossary.md)
- [Library tools](https://developer.goacoustic.com/acoustic-personalization/docs/personalization-library-tools.md): Use the helper functions in Personalization Library
- [Library response codes](https://developer.goacoustic.com/acoustic-personalization/docs/personalization-library-response-codes.md): Personalization Library response codes
- [Personalization library all versions history](https://developer.goacoustic.com/acoustic-personalization/docs/personalization-library-all-versions-history.md): Personalization library versions
- [Web page freeze due to Exchange script in GTM](https://developer.goacoustic.com/acoustic-personalization/docs/web-page-freeze-due-to-exchange-script-in-gtm.md)
- [Event flow issues in Exchange](https://developer.goacoustic.com/acoustic-personalization/docs/event-flow-issues-in-exchange.md)
## Recipes
- [Render your personalized content based on the content type](https://developer.goacoustic.com/acoustic-personalization/recipes/render-your-personalized-content-based-on-the-content-type.md)